diff --git a/docs-src/webqueue2api Package/Configuration.md b/docs-src/webqueue2api Package/Configuration.md new file mode 100644 index 0000000..e379c3d --- /dev/null +++ b/docs-src/webqueue2api Package/Configuration.md @@ -0,0 +1,46 @@ +The configuration of webqueue2api can be managed in two different ways: + +- At launch with a configuration file in the same directory as the virtual environment +- At runtime by modifying the `webqueue2api.config` symbol directly + +## Configuration File +On import, a [ConfigParser INI formatted file](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure) is read for configuartion options. This file must be located in the same directory as the virtual environment folder and must be named `webqueue2api_config.ini`. + +!!! example "A Full Config File" + ```ini + [parser] + # Absolute path to directory containing queue data. + # Default: /home/pier/e/queue/Mail + queue_directory = /etc/queue-cli/queues + + # List of queues to ignore. (Comma and space ", " delimited.) + # Default: archives, drafts, inbox, coral + queues_to_ignore = dogs, cats, particularly_pugs + + [api] + # Runtime configuration for secure production or convenient development settings. + # Valid options are: prod | dev + # Default: prod + environment = dev + + # Token used to encrypt JWT payloads. + # Default: webqueue2api.api.config.generate_random_string + jwt_secret_key = uV0liG9$YgcGE7J! + ``` + +## Changing Settings at Runtime +Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol. + +These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use. + +!!! example "Changing the parser's queue directory by editing object values." + ```python + import webqueue2api + + # Load Queue from default directory + ce_queue = Queue("ce") + + # load Queue from modified directory + webqueue2api.config.parser.queue_directory = "/absolute/path" + other_queue = Queue("other") + ``` \ No newline at end of file diff --git a/docs-src/webqueue2api Package/Getting Started.md b/docs-src/webqueue2api Package/Getting Started.md index 69c6a0f..12db716 100644 --- a/docs-src/webqueue2api Package/Getting Started.md +++ b/docs-src/webqueue2api Package/Getting Started.md @@ -10,6 +10,31 @@ The webqueue2api Package has the following structure: ## Basic Usage +!!! example "Load all queues." + ```python + import webqueue2api + all_queues = webqueue2api.load_queues() + for queue in all_queues: + print(f"{queue.name} has {len(queue.items)} items." + ``` + ```python + # Expected Output + "tech has 72 items" + "ce has 38 items" + ... + ``` + +!!! example "Load some queues." + ```python + import webqueue2api + all_queues = webqueue2api.load_queues("che", "tech", "ce") + print( len( all_queues ) ) + ``` + ```python + # Expected Output + 3 + ``` + !!! example "Load a queue and get the number of items in it." ```python import webqueue2api diff --git a/docs-src/webqueue2api Package/Package Structure.md b/docs-src/webqueue2api Package/Package Structure.md index cd45585..6b4c370 100644 --- a/docs-src/webqueue2api Package/Package Structure.md +++ b/docs-src/webqueue2api Package/Package Structure.md @@ -5,21 +5,4 @@ The webqueue2api Package consists of four packages in total: - `webqueue2api`: The root packages. This contains both the `api` and the `parser` packages as well as global configuration. - `api`: Contains a [Flask](https://flask.palletsprojects.com/) app that can be used with any WSGI server to host the webqueue2 API and utilities such as authentication code. - `resources`: Contains [Flask-RESTful](https://flask-restful.readthedocs.io/en/latest/) resources for the webqueue2 API. - - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors. - -## Configuration -Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol. - -These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use. - -!!! example "Changing the parser's queue directory by editing object values." - ```python - import webqueue2api - - # Load Queue from default directory - ce_queue = Queue("ce") - - # load Queue from modified directory - webqueue2api.config.parser.queue_directory = "/absolute/path" - other_queue = Queue("other") - ``` \ No newline at end of file + - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors. \ No newline at end of file diff --git a/docs-src/webqueue2api Package/awesome-pages.yaml b/docs-src/webqueue2api Package/awesome-pages.yaml index a33b701..9c82ab4 100644 --- a/docs-src/webqueue2api Package/awesome-pages.yaml +++ b/docs-src/webqueue2api Package/awesome-pages.yaml @@ -2,5 +2,6 @@ # See: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin nav: - Getting Started.md + - Configuration.md - Package Structure.md - ... \ No newline at end of file