diff options
| -rw-r--r-- | README.md | 25 | ||||
| -rw-r--r-- | docs/Makefile | 20 | ||||
| -rw-r--r-- | docs/make.bat | 35 | ||||
| -rw-r--r-- | docs/source/api-reference.rst | 2 | ||||
| -rw-r--r-- | docs/source/conf.py | 62 | ||||
| -rw-r--r-- | docs/source/getting-started.rst | 141 | ||||
| -rw-r--r-- | docs/source/index.rst | 22 | ||||
| -rw-r--r-- | docs/source/license.rst | 4 |
8 files changed, 20 insertions, 291 deletions
@@ -37,11 +37,17 @@ You can also use [Poetry](https://python-poetry.org). $ poetry install config-file -E yaml -E toml ``` -## Usage Overview +## Usage For this overview, let's say you have the following `ini` file you want to manipulate. +Do note, however, that the `ini` format is the oddest format that +`ConfigFile` supports in that it has no formal specification and is +not type aware. When retrieving items from the file, it will return +them as strings by default. Others are more type aware and do not +require as much type coercion. + ```ini [section] num_key = 5 @@ -284,17 +290,26 @@ config.restore_original() ``` However, if we have a specific path elsewhere that this original configuration file is or it -is named differently than what the default expects, we can utilize the `original_file_path` +is named differently than what the default expects, we can utilize the `original_path` keyword argument. ```python -config.restore_original(original_file_path="~/some-project/original-configs/config.ini") +config.restore_original(original_path="~/some-project/original-configs/config.ini") ``` -## Documentation +## Format Versions Supported + +| Format | Specification version supported | +| ------------- | ------------- | +| INI | No official specification. | +| JSON | [RFC 7159](https://tools.ietf.org/html/rfc7159.html) | +| YAML | [v1.2](https://yaml.org/spec/1.2/spec.html) | +| TOML | [v1.0.0-rc.1](https://github.com/toml-lang/toml/releases/tag/v1.0.0-rc.1) | -Full documentation and API reference is available at https://config-file.readthedocs.io +For `ini` and `json`, Python's standard library modules are used. +Regarding `ini`, there is no formal specification so the syntax that configparser +supports is what is supported here. ## License diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
- exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/docs/source/api-reference.rst b/docs/source/api-reference.rst deleted file mode 100644 index 4ea8c91..0000000 --- a/docs/source/api-reference.rst +++ /dev/null @@ -1,2 +0,0 @@ -API Reference -=============
\ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 69cfce0..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,62 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - -import os -import sys - -sys.path.insert(0, os.path.abspath("../..")) - - -# -- Project information ----------------------------------------------------- - -project = "Config File" -copyright = "2020, Eugene Triguba" -author = "Eugene Triguba" - -# The full version, including alpha/beta/rc tags -release = "0.10.0" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosectionlabel", - "sphinx.ext.napoleon", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# Specify the master doc for read the docs -master_doc = "index" - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst deleted file mode 100644 index 92264a3..0000000 --- a/docs/source/getting-started.rst +++ /dev/null @@ -1,141 +0,0 @@ -Getting Started -=============== - -Example -------- - -The ``config_file`` package exposes ``ConfigFile``, ``ParsingError``, -and ``BaseParser`` to the public API. - -Sample Configuration File -~~~~~~~~~~~~~~~~~~~~~~~~~ - -``config.ini`` - -.. code:: ini - - [calendar] - today = monday - start_week_on_sunday = false - today_index = 0 - quarter_hours_passed = 0.25 - -Create a ConfigFile -~~~~~~~~~~~~~~~~~~~ - -.. code:: python - - from config_file import ConfigFile - - config = ConfigFile("~/.config/test/config.ini") - -Output your config file as a string -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: python - - config.stringify() - >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 0\nquarter_hours_passed = 0.25\n\n' - -Retrieve values or sections -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A section.key format is used for retrieving and setting values. - -.. code:: python - - # Values from the config file are automatically parsed - config.get("calendar.start_week_on_sunday") - >>> False - - # Unless you don't want them to be parsed - config.get("calendar.start_week_on_sunday", parse_types=False) - >>> 'false' - - config.get("calendar") - >>> {'today': 'monday', 'start_week_on_sunday': False, 'today_index': 0, 'quarter_hours_passed': 0.25} - -Set values -~~~~~~~~~~ - -.. code:: python - - config.set("calendar.today_index", 20) - >>> True - config.stringify() - >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n' - - # If you specify a section that isn't in your config file, the section and the key are added for you. - config.set("week.tuesday_index", 2) - >>> True - config.stringify() - >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n[week]\ntuesday_index = 2\n\n' - -.. _delete-sections-or-keyvalue-pairs: - -Delete sections or key/value pairs. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: python - - config.delete('week') - >>> True - config.stringify() - >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n' - - config.delete('calendar.today') - >>> True - config.stringify() - >>> '[calendar]\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n' - -Check whether you have a particular section or key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: python - - config.has('calendar') - >>> True - - config.has('week') - >>> False - - config.has('calendar.start_week_on_sunday') - >>> True - -Save when you're done -~~~~~~~~~~~~~~~~~~~~~ - -Write the contents of the file back out. ``set()`` and ``delete()`` both -modify the contents of the file and require a call to ``save()`` to -write those changes back out. - -.. code:: python - - config.save() - >>> True - -Restore the file back to its original -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The current configuration file would be deleted and replaced by a copy -of the original. By default, since our passed in config file was at path -``~/.config/test/config.ini``, ``restore_original()`` will look for -``~/.config/test/config.original.ini``. - -.. code:: python - - config.restore_original() - >>> True - - # But you can also specify the original config file explicitly. - config.restore_original(original_file_path="~/some_other_directory/this_is_actually_the_original.ini") - >>> True - -Using your own parser ---------------------- - -You can still use config file, even if you don't use one of our supported -configuration formats. The ``ConfigFile`` object swaps in the parser it needs -based on the file format. However, the constructor takes in an optional -parser argument that you can use to supply your own custom parser. The only -requirement is that the parser must be a concrete implementation of ``BaseParser``.
\ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 6b59715..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -Config File Documentation -========================= - -Config File is a package that allows you to easily manipulate your configuration -files whether they are in INI, JSON, YAML, or TOML. - -**Table of Contents:** - -.. toctree:: - :maxdepth: 2 - - getting-started - api-reference - license - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/license.rst b/docs/source/license.rst deleted file mode 100644 index 01f3963..0000000 --- a/docs/source/license.rst +++ /dev/null @@ -1,4 +0,0 @@ -License -======= - -.. include:: ../../LICENSE
\ No newline at end of file |