| Name | edq-utils JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | Common utilities used by EduLinq Python projects. |
| upload_time | 2025-10-27 15:32:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 EduLinq
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
education
utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
json5
platformdirs
requests
requests-toolbelt
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# EduLinq Python Utilities
Common utilities used by EduLinq Python projects.
Links:
- [API Reference](https://edulinq.github.io/python-utils)
- [Installation / Requirements](#installation--requirements)
- [Configuration System](#configuration-system)
- [Configuration Sources](#configuration-sources)
## Installation / Requirements
This project requires [Python](https://www.python.org/) >= 3.8.
The project can be installed from PyPi with:
```
pip3 install edq-utils
```
Standard Python requirements are listed in `pyproject.toml`.
The project and Python dependencies can be installed from source with:
```
pip3 install .
```
## Configuration System
This project provides a configuration system that supplies options (e.g., username, password) to a command-line interface (CLI) tool.
The configuration system follows a tiered order, allowing options to be specified and overridden from both files and command-line options.
### Configuration Sources
In addition to CLI options, the configuration system loads options from [JSON](https://en.wikipedia.org/wiki/JSON) files located across multiple directories.
By default, configuration files are named `edq-config.json`.
This value is customizable, but this document will assume the default is used.
For example, a configuration file containing the `user` and `pass` options might look like this:
```json
{
"user": "alice",
"pass": "password123"
}
```
The table below summarizes the configuration sources in the order they are evaluated.
Values from earlier sources can be overwritten by values from later sources.
| Source | Description |
| :----- | :---------- |
| Global | Loaded from a file in a user-specific location, which is platform-dependent. |
| Local | Loaded from a file in the current or nearest ancestor directory. |
| CLI File | Loaded from one or more explicitly provided configuration files through the CLI. |
| CLI | Loaded from the command line. |
The system produces an error if a global or local configuration file is unreadable (but not missing), or if a CLI-specified file is unreadable or missing.
#### Global Configuration
Global configuration are options that are user specific and stick with the user between projects, these are well suited for options like login credentials.
The global configuration file defaults to `<platform-specific user configuration location>/edq-config.json`.
The configuration location is chosen according to the [XDG standard](https://en.wikipedia.org/wiki/Freedesktop.org#Base_Directory_Specification) (implemented by [platformdirs](https://github.com/tox-dev/platformdirs)).
Below are examples of user-specific configuration file paths for different operating systems:
- Linux -- `/home/<user>/.config/edq-config.json`
- Mac -- `/Users/<user>/Library/Application Support/edq-config.json`
- Windows -- `C:\Users\<user>\AppData\Local\edq-config.json`
The default global configuration location can be changed by passing a path to `--config-global` through the command line.
Below is an example command for specifying a global configuration path from the CLI:
```sh
python3 -m edq.cli.config.list --config-global ~/.config/custom-config.json
```
#### Local Configuration
Local configuration are options that are specific to a project or directory, like a project's build directory.
Local configuration files are searched in multiple locations, the first file found is used.
The local config search order is:
1. `edq-config.json` in the current directory.
2. A legacy file in the current directory (only if a legacy file is preconfigured).
3. `edq-config.json` in any ancestor directory on the path to root (including root itself).
#### CLI-Specified Config Files
CLI config files are options specified on the command line via a file.
These are useful for a common set of options you don’t need every time, such as login credentials for different user.
Any files passed via `--config-file` will be loaded in the order they appear on the command line.
Options from later files override options from previous files.
Below is an example of a CLI specified configuration paths:
```sh
python3 -m edq.cli.config.list --config-file ./edq-config.json --config-file ~/.secrets/edq-config.json
```
#### CLI Configuration
CLI configurations are options specified directly on the command line, these are useful for quick option overrides without editing config files.
Configuration options are passed to the command line by the `--config` flag in this format `<key>=<value>`.
The provided values overrides the values from configuration files.
Configuration options are structured as key value pairs and keys cannot contain the "=" character.
Below is an example of specifying a configuration option directly from the CLI:
```sh
python3 -m edq.cli.config.list --config user=alice --config pass=password123
```
#### CLI Config Options
The table below lists common configuration CLI options available for CLI tools using this library.
| CLI Option | Description |
| :-------------- | :---------- |
|`--config-global` | Override the global config file location. |
|`--config-file` | Load configuration options from a CLI specified file. |
| `--config` | Provide additional options to a CLI command. |
| `--help` | Display standard help text and the default global configuration file path for the current platform. |
Raw data
{
"_id": null,
"home_page": null,
"name": "edq-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "education, utilities",
"author": null,
"author_email": "Eriq Augustine <eriq@edulinq.org>",
"download_url": "https://files.pythonhosted.org/packages/ed/60/f753e4cd0c95e198efad7424863c4c5c8b84f211522bde20bb22c293eb19/edq_utils-0.1.7.tar.gz",
"platform": null,
"description": "# EduLinq Python Utilities\n\nCommon utilities used by EduLinq Python projects.\n\nLinks:\n - [API Reference](https://edulinq.github.io/python-utils)\n - [Installation / Requirements](#installation--requirements)\n - [Configuration System](#configuration-system)\n - [Configuration Sources](#configuration-sources)\n\n## Installation / Requirements\n\nThis project requires [Python](https://www.python.org/) >= 3.8.\n\nThe project can be installed from PyPi with:\n```\npip3 install edq-utils\n```\n\nStandard Python requirements are listed in `pyproject.toml`.\nThe project and Python dependencies can be installed from source with:\n```\npip3 install .\n```\n\n## Configuration System\n\nThis project provides a configuration system that supplies options (e.g., username, password) to a command-line interface (CLI) tool.\nThe configuration system follows a tiered order, allowing options to be specified and overridden from both files and command-line options.\n\n### Configuration Sources\n\nIn addition to CLI options, the configuration system loads options from [JSON](https://en.wikipedia.org/wiki/JSON) files located across multiple directories.\nBy default, configuration files are named `edq-config.json`.\nThis value is customizable, but this document will assume the default is used.\n\nFor example, a configuration file containing the `user` and `pass` options might look like this:\n```json\n{\n \"user\": \"alice\",\n \"pass\": \"password123\"\n}\n```\n\nThe table below summarizes the configuration sources in the order they are evaluated.\nValues from earlier sources can be overwritten by values from later sources.\n\n| Source | Description |\n| :----- | :---------- |\n| Global | Loaded from a file in a user-specific location, which is platform-dependent. |\n| Local | Loaded from a file in the current or nearest ancestor directory. |\n| CLI File | Loaded from one or more explicitly provided configuration files through the CLI. |\n| CLI | Loaded from the command line. |\n\nThe system produces an error if a global or local configuration file is unreadable (but not missing), or if a CLI-specified file is unreadable or missing.\n\n#### Global Configuration\n\nGlobal configuration are options that are user specific and stick with the user between projects, these are well suited for options like login credentials.\nThe global configuration file defaults to `<platform-specific user configuration location>/edq-config.json`.\nThe configuration location is chosen according to the [XDG standard](https://en.wikipedia.org/wiki/Freedesktop.org#Base_Directory_Specification) (implemented by [platformdirs](https://github.com/tox-dev/platformdirs)).\nBelow are examples of user-specific configuration file paths for different operating systems:\n - Linux -- `/home/<user>/.config/edq-config.json`\n - Mac -- `/Users/<user>/Library/Application Support/edq-config.json`\n - Windows -- `C:\\Users\\<user>\\AppData\\Local\\edq-config.json`\n\nThe default global configuration location can be changed by passing a path to `--config-global` through the command line.\n\nBelow is an example command for specifying a global configuration path from the CLI:\n```sh\npython3 -m edq.cli.config.list --config-global ~/.config/custom-config.json\n```\n\n#### Local Configuration\n\nLocal configuration are options that are specific to a project or directory, like a project's build directory.\nLocal configuration files are searched in multiple locations, the first file found is used.\nThe local config search order is:\n1. `edq-config.json` in the current directory.\n2. A legacy file in the current directory (only if a legacy file is preconfigured).\n3. `edq-config.json` in any ancestor directory on the path to root (including root itself).\n\n#### CLI-Specified Config Files\n\nCLI config files are options specified on the command line via a file.\nThese are useful for a common set of options you don\u2019t need every time, such as login credentials for different user.\nAny files passed via `--config-file` will be loaded in the order they appear on the command line.\nOptions from later files override options from previous files.\n\nBelow is an example of a CLI specified configuration paths:\n```sh\npython3 -m edq.cli.config.list --config-file ./edq-config.json --config-file ~/.secrets/edq-config.json\n```\n\n#### CLI Configuration\n\nCLI configurations are options specified directly on the command line, these are useful for quick option overrides without editing config files.\nConfiguration options are passed to the command line by the `--config` flag in this format `<key>=<value>`.\nThe provided values overrides the values from configuration files.\nConfiguration options are structured as key value pairs and keys cannot contain the \"=\" character.\n\nBelow is an example of specifying a configuration option directly from the CLI:\n```sh\npython3 -m edq.cli.config.list --config user=alice --config pass=password123\n```\n\n#### CLI Config Options\n\nThe table below lists common configuration CLI options available for CLI tools using this library.\n\n| CLI Option | Description |\n| :-------------- | :---------- |\n|`--config-global` | Override the global config file location. |\n|`--config-file` | Load configuration options from a CLI specified file. |\n| `--config` | Provide additional options to a CLI command. |\n| `--help` | Display standard help text and the default global configuration file path for the current platform. |\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 EduLinq\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Common utilities used by EduLinq Python projects.",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/edulinq/python-utils",
"Repository": "https://github.com/edulinq/python-utils"
},
"split_keywords": [
"education",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0fbcb5ef1e7df9a0a9a6d5baf25ec72ec80564495b95129a80e4b9941ed567e0",
"md5": "fa63fb2757930af03c1c265ab16db6ec",
"sha256": "504179d42a01626a09b2e4d671cb03d845ee4de8a1a1b45cff7846c5f539f37c"
},
"downloads": -1,
"filename": "edq_utils-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa63fb2757930af03c1c265ab16db6ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 77598,
"upload_time": "2025-10-27T15:32:43",
"upload_time_iso_8601": "2025-10-27T15:32:43.206234Z",
"url": "https://files.pythonhosted.org/packages/0f/bc/b5ef1e7df9a0a9a6d5baf25ec72ec80564495b95129a80e4b9941ed567e0/edq_utils-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ed60f753e4cd0c95e198efad7424863c4c5c8b84f211522bde20bb22c293eb19",
"md5": "42880649605325f2b5e6b7083f4614a3",
"sha256": "950c3b51361daa543680023adcce8b566768353e1a20b8d4ceeda62c6884099a"
},
"downloads": -1,
"filename": "edq_utils-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "42880649605325f2b5e6b7083f4614a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 80846,
"upload_time": "2025-10-27T15:32:44",
"upload_time_iso_8601": "2025-10-27T15:32:44.080420Z",
"url": "https://files.pythonhosted.org/packages/ed/60/f753e4cd0c95e198efad7424863c4c5c8b84f211522bde20bb22c293eb19/edq_utils-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 15:32:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "edulinq",
"github_project": "python-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "json5",
"specs": [
[
">=",
"0.9.14"
]
]
},
{
"name": "platformdirs",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "requests-toolbelt",
"specs": []
}
],
"lcname": "edq-utils"
}
