<!--
=====================================
generator=datazen
version=3.1.4
hash=625e7606ffc71be06c919432e86f94e2
=====================================
-->
# rcmpy ([1.5.5](https://pypi.org/project/rcmpy/))
[](https://pypi.org/project/rcmpy/)
[](https://codecov.io/github/vkottler/rcmpy)
*A configuration-file management system.*
## Documentation
### Generated
* By [sphinx-apidoc](https://vkottler.github.io/python/sphinx/rcmpy)
(What's [`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)?)
* By [pydoc](https://vkottler.github.io/python/pydoc/rcmpy.html)
(What's [`pydoc`](https://docs.python.org/3/library/pydoc.html)?)
## Python Version Support
This package is tested with the following Python minor versions:
* [`python3.10`](https://docs.python.org/3.10/)
* [`python3.11`](https://docs.python.org/3.11/)
* [`python3.12`](https://docs.python.org/3.12/)
## Platform Support
This package is tested on the following platforms:
* `ubuntu-latest`
* `macos-latest`
* `windows-latest`
# Introduction
This project aims to simplify management of user configuration files, user (or
system-wide) package installations, system settings and more on a variety of
platforms.
Reasons to use it:
1. Simplify bootstrapping a fresh system to a "developer workstation" in as few
steps as possible
1. This can be a simpler options for teams or individuals who don't have
infrastructure to manage system-install images, system-distribution build
systems, other kinds of provisioning automation, etc.
1. Normalize software configurations for a team of developers, but still allow
personalized overrides when desired (e.g. text-editor or terminal configs)
1. This can help make your team or organization's development environment
more approachable to new or inexperienced developers (ask yourself this:
are the code changes usually even the hard part?)
1. Relies on a minimal [data repository](md/data_repository.md) that can be
managed with version control, shared by multiple people, open source to provide
examples to the community, etc.
1. This enables a workflow for adding, removing, updating and re-configuring
software used by a project-ecosystem over time
# Getting Started
This package attempts to adhere to the
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
It keeps stateful formation that needs to persist between command invocations
in a `rcmpy` sub-directory of the user-state directory controlled
by `XDG_STATE_HOME` (or the default: `$HOME/.local/state`).
One tracked piece of stateful information is the location of the current
[data repository](md/data_repository.md). If this is not changed (via the `use`
command), it checks a `rcmpy/default` sub-directory in the
user-config directory controlled by `XDG_CONFIG_HOME` (or the default:
`$HOME/.config`).
## System Requirements
1. It is assumed that the system has a [Python](https://www.python.org/)
executable and [pip](https://pypi.org/project/pip/) is available to it as
an installed package (can be checked with: `python[3][.exe] -m pip --version`
or `pip[3][.exe] --version`).
2. A mechanism to obtain a [data repository](md/data_repository.md) via a
network connection, if one won't be created from scratch (e.g. a
[git](https://git-scm.com/) client).
## Installation and Setup
1. Install the package with `pip[3][.exe] --user rcmpy` or
`python[3][.exe] -m pip --user rcmpy`.
1. Test that `rcmpy` is now a shell command with
`rcmpy --version`.
1. If not, you may need to invoke
`rcmpy` directly from `$HOME/.local/bin` or
`%APPDATA%\Python`.
(see the
[pip documentation](https://pip.pypa.io/en/stable/user_guide/?highlight=--user#user-installs)
for more info).
1. Run `rcmpy use` to view the default
[data repository](md/data_repository.md) location (printed to the console):
```
$ rcmpy use
rcmpy.state - INFO - Using directory '/home/vkottler/.config/rcmpy/default'.
```
4. Begin setting up your [data repository](md/data_repository.md) in this
location, or:
1. Download (or `git clone`) one to that default location.
1. Create a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) at
that location, pointing to one.
1. Run `rcmpy use <path>` to point `rcmpy` at
an existing one at any arbitrary location.
5. Run `rcmpy apply` to perform tasks specified in the
[top-level configuration file](md/data_repository.md#top-level-configuration).
# Command-line Options
```
$ ./venv3.12/bin/rcmpy -h
usage: rcmpy [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]
{apply,dump,use,variant,watch,noop} ...
A configuration-file management system.
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose set to increase logging verbosity
-q, --quiet set to reduce output
--curses whether or not to use curses.wrapper when starting
--no-uvloop whether or not to disable uvloop as event loop driver
-C DIR, --dir DIR execute from a specific directory
commands:
{apply,dump,use,variant,watch,noop}
set of available commands
apply apply any pending changes from the active data
repository
dump dump template data to stdout as JSON
use set the directory to use as the rcmpy data repository
variant set the variant of configuration data to use
watch do a task whenever a file in a specified directory
changes
noop command stub (does nothing)
```
## Sub-command Options
### `apply`
```
$ ./venv3.12/bin/rcmpy apply -h
usage: rcmpy apply [-h] [-f] [-d]
options:
-h, --help show this help message and exit
-f, --force whether or not to forcibly render all outputs
-d, --dry-run whether or not to update output files
```
### `dump`
```
$ ./venv3.12/bin/rcmpy dump -h
usage: rcmpy dump [-h]
options:
-h, --help show this help message and exit
```
### `use`
```
$ ./venv3.12/bin/rcmpy use -h
usage: rcmpy use [-h] [-d] [directory]
positional arguments:
directory the directory to use
options:
-h, --help show this help message and exit
-d, --default sets the directory back to the package default
```
### `variant`
```
$ ./venv3.12/bin/rcmpy variant -h
usage: rcmpy variant [-h] [-d] [variant]
positional arguments:
variant new variant to use
options:
-h, --help show this help message and exit
-d, --default sets the directory back to the package default
```
### `watch`
```
$ ./venv3.12/bin/rcmpy watch -h
usage: rcmpy watch [-h] [-p POLL_RATE] [-s] [-i] [-n] directory cmd [cmd ...]
positional arguments:
directory directory to watch for file changes
cmd command to run
options:
-h, --help show this help message and exit
-p POLL_RATE, --poll-rate POLL_RATE
poll period in seconds (default: 0.1s)
-s, --shell set to run a shell command
-i, --single-pass only run a single iteration
-n, --no-change don't act on changed files, only the overall set of
files changing (added or removed)
```
# Internal Dependency Graph
A coarse view of the internal structure and scale of
`rcmpy`'s source.
Generated using [pydeps](https://github.com/thebjorn/pydeps) (via
`mk python-deps`).
Raw data
{
"_id": null,
"home_page": "https://github.com/vkottler/rcmpy",
"name": "rcmpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Vaughn Kottler <vaughnkottler@gmail.com>",
"keywords": null,
"author": "Vaughn Kottler",
"author_email": "Vaughn Kottler <vaughnkottler@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/9d/1b9238250dadd6909024e48d34be129e62d011d04e0240bb7418ac3dd43a/rcmpy-1.5.5.tar.gz",
"platform": null,
"description": "<!--\n =====================================\n generator=datazen\n version=3.1.4\n hash=625e7606ffc71be06c919432e86f94e2\n =====================================\n-->\n\n# rcmpy ([1.5.5](https://pypi.org/project/rcmpy/))\n\n[](https://pypi.org/project/rcmpy/)\n\n[](https://codecov.io/github/vkottler/rcmpy)\n\n\n\n*A configuration-file management system.*\n\n## Documentation\n\n### Generated\n\n* By [sphinx-apidoc](https://vkottler.github.io/python/sphinx/rcmpy)\n(What's [`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)?)\n* By [pydoc](https://vkottler.github.io/python/pydoc/rcmpy.html)\n(What's [`pydoc`](https://docs.python.org/3/library/pydoc.html)?)\n\n## Python Version Support\n\nThis package is tested with the following Python minor versions:\n\n* [`python3.10`](https://docs.python.org/3.10/)\n* [`python3.11`](https://docs.python.org/3.11/)\n* [`python3.12`](https://docs.python.org/3.12/)\n\n## Platform Support\n\nThis package is tested on the following platforms:\n\n* `ubuntu-latest`\n* `macos-latest`\n* `windows-latest`\n\n# Introduction\n\nThis project aims to simplify management of user configuration files, user (or\nsystem-wide) package installations, system settings and more on a variety of\nplatforms.\n\nReasons to use it:\n1. Simplify bootstrapping a fresh system to a \"developer workstation\" in as few\nsteps as possible\n 1. This can be a simpler options for teams or individuals who don't have\n infrastructure to manage system-install images, system-distribution build\n systems, other kinds of provisioning automation, etc.\n1. Normalize software configurations for a team of developers, but still allow\npersonalized overrides when desired (e.g. text-editor or terminal configs)\n 1. This can help make your team or organization's development environment\n more approachable to new or inexperienced developers (ask yourself this:\n are the code changes usually even the hard part?)\n1. Relies on a minimal [data repository](md/data_repository.md) that can be\nmanaged with version control, shared by multiple people, open source to provide\nexamples to the community, etc.\n 1. This enables a workflow for adding, removing, updating and re-configuring\n software used by a project-ecosystem over time\n\n# Getting Started\n\nThis package attempts to adhere to the\n[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).\nIt keeps stateful formation that needs to persist between command invocations\nin a `rcmpy` sub-directory of the user-state directory controlled\nby `XDG_STATE_HOME` (or the default: `$HOME/.local/state`).\n\nOne tracked piece of stateful information is the location of the current\n[data repository](md/data_repository.md). If this is not changed (via the `use`\ncommand), it checks a `rcmpy/default` sub-directory in the\nuser-config directory controlled by `XDG_CONFIG_HOME` (or the default:\n`$HOME/.config`).\n\n## System Requirements\n\n1. It is assumed that the system has a [Python](https://www.python.org/)\nexecutable and [pip](https://pypi.org/project/pip/) is available to it as\nan installed package (can be checked with: `python[3][.exe] -m pip --version`\nor `pip[3][.exe] --version`).\n2. A mechanism to obtain a [data repository](md/data_repository.md) via a\nnetwork connection, if one won't be created from scratch (e.g. a\n[git](https://git-scm.com/) client).\n\n## Installation and Setup\n\n1. Install the package with `pip[3][.exe] --user rcmpy` or\n`python[3][.exe] -m pip --user rcmpy`.\n1. Test that `rcmpy` is now a shell command with\n`rcmpy --version`.\n 1. If not, you may need to invoke\n `rcmpy` directly from `$HOME/.local/bin` or\n `%APPDATA%\\Python`.\n(see the\n[pip documentation](https://pip.pypa.io/en/stable/user_guide/?highlight=--user#user-installs)\nfor more info).\n1. Run `rcmpy use` to view the default\n[data repository](md/data_repository.md) location (printed to the console):\n\n```\n$ rcmpy use\nrcmpy.state - INFO - Using directory '/home/vkottler/.config/rcmpy/default'.\n```\n\n4. Begin setting up your [data repository](md/data_repository.md) in this\nlocation, or:\n 1. Download (or `git clone`) one to that default location.\n 1. Create a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) at\n that location, pointing to one.\n 1. Run `rcmpy use <path>` to point `rcmpy` at\n an existing one at any arbitrary location.\n5. Run `rcmpy apply` to perform tasks specified in the\n[top-level configuration file](md/data_repository.md#top-level-configuration).\n\n# Command-line Options\n\n```\n$ ./venv3.12/bin/rcmpy -h\n\nusage: rcmpy [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]\n {apply,dump,use,variant,watch,noop} ...\n\nA configuration-file management system.\n\noptions:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -v, --verbose set to increase logging verbosity\n -q, --quiet set to reduce output\n --curses whether or not to use curses.wrapper when starting\n --no-uvloop whether or not to disable uvloop as event loop driver\n -C DIR, --dir DIR execute from a specific directory\n\ncommands:\n {apply,dump,use,variant,watch,noop}\n set of available commands\n apply apply any pending changes from the active data\n repository\n dump dump template data to stdout as JSON\n use set the directory to use as the rcmpy data repository\n variant set the variant of configuration data to use\n watch do a task whenever a file in a specified directory\n changes\n noop command stub (does nothing)\n\n```\n\n## Sub-command Options\n\n### `apply`\n\n```\n$ ./venv3.12/bin/rcmpy apply -h\n\nusage: rcmpy apply [-h] [-f] [-d]\n\noptions:\n -h, --help show this help message and exit\n -f, --force whether or not to forcibly render all outputs\n -d, --dry-run whether or not to update output files\n\n```\n\n### `dump`\n\n```\n$ ./venv3.12/bin/rcmpy dump -h\n\nusage: rcmpy dump [-h]\n\noptions:\n -h, --help show this help message and exit\n\n```\n\n### `use`\n\n```\n$ ./venv3.12/bin/rcmpy use -h\n\nusage: rcmpy use [-h] [-d] [directory]\n\npositional arguments:\n directory the directory to use\n\noptions:\n -h, --help show this help message and exit\n -d, --default sets the directory back to the package default\n\n```\n\n### `variant`\n\n```\n$ ./venv3.12/bin/rcmpy variant -h\n\nusage: rcmpy variant [-h] [-d] [variant]\n\npositional arguments:\n variant new variant to use\n\noptions:\n -h, --help show this help message and exit\n -d, --default sets the directory back to the package default\n\n```\n\n### `watch`\n\n```\n$ ./venv3.12/bin/rcmpy watch -h\n\nusage: rcmpy watch [-h] [-p POLL_RATE] [-s] [-i] [-n] directory cmd [cmd ...]\n\npositional arguments:\n directory directory to watch for file changes\n cmd command to run\n\noptions:\n -h, --help show this help message and exit\n -p POLL_RATE, --poll-rate POLL_RATE\n poll period in seconds (default: 0.1s)\n -s, --shell set to run a shell command\n -i, --single-pass only run a single iteration\n -n, --no-change don't act on changed files, only the overall set of\n files changing (added or removed)\n\n```\n\n# Internal Dependency Graph\n\nA coarse view of the internal structure and scale of\n`rcmpy`'s source.\nGenerated using [pydeps](https://github.com/thebjorn/pydeps) (via\n`mk python-deps`).\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A configuration-file management system.",
"version": "1.5.5",
"project_urls": {
"Homepage": "https://github.com/vkottler/rcmpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a81e04c7a5f7669b37fc377db1a3cd76bc95a528201bbd7153b03db9500590e",
"md5": "c1ef267375d48182ae9005c95323fbe0",
"sha256": "b4bcba1a59336d12509cbe2182f6a6bb9c617b94d52f98934fbbe53f8e7d8436"
},
"downloads": -1,
"filename": "rcmpy-1.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1ef267375d48182ae9005c95323fbe0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27045,
"upload_time": "2024-05-15T07:39:48",
"upload_time_iso_8601": "2024-05-15T07:39:48.476058Z",
"url": "https://files.pythonhosted.org/packages/2a/81/e04c7a5f7669b37fc377db1a3cd76bc95a528201bbd7153b03db9500590e/rcmpy-1.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f99d1b9238250dadd6909024e48d34be129e62d011d04e0240bb7418ac3dd43a",
"md5": "7059fe47dadb8fe8a9cd5936b1ab8c1b",
"sha256": "74502b1354d099603f99b1ccace97ce2215b9b47df96c04182393e0f2ca1912c"
},
"downloads": -1,
"filename": "rcmpy-1.5.5.tar.gz",
"has_sig": false,
"md5_digest": "7059fe47dadb8fe8a9cd5936b1ab8c1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22683,
"upload_time": "2024-05-15T07:39:49",
"upload_time_iso_8601": "2024-05-15T07:39:49.988955Z",
"url": "https://files.pythonhosted.org/packages/f9/9d/1b9238250dadd6909024e48d34be129e62d011d04e0240bb7418ac3dd43a/rcmpy-1.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-15 07:39:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vkottler",
"github_project": "rcmpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rcmpy"
}
JSON
