diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index c65d7ef..3c1c720 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -21,6 +21,7 @@ jobs: - "3.8" - "3.9" - "3.10" + - "3.11" system: - ubuntu-latest - macos-latest diff --git a/README.md b/README.md index c74b550..9b3ba15 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ===================================== generator=datazen version=3.1.0 - hash=c7403ee8217c0260dff97f3404f3af77 + hash=fe3e09e0d89218f917b0f128f402465c ===================================== --> @@ -27,6 +27,7 @@ This package is tested with the following Python minor versions: * [`python3.8`](https://docs.python.org/3.8/) * [`python3.9`](https://docs.python.org/3.9/) * [`python3.10`](https://docs.python.org/3.10/) +* [`python3.11`](https://docs.python.org/3.11/) ## Platform Support @@ -38,6 +39,41 @@ This package is tested on the following platforms: # 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 information that needs to persist between command invocations +in a `rcmpy` sub-directory in 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`). + # Command-line Options ``` @@ -64,6 +100,51 @@ commands: ``` +## Sub-command Options + +### `apply` + +``` +$ ./venv3.8/bin/rcmpy apply -h + +usage: rcmpy apply [-h] + +optional arguments: + -h, --help show this help message and exit + +``` + +### `use` + +``` +$ ./venv3.8/bin/rcmpy use -h + +usage: rcmpy use [-h] [-d] [directory] + +positional arguments: + directory the directory to use + +optional arguments: + -h, --help show this help message and exit + -d, --default sets the directory back to the package default + +``` + +### `variant` + +``` +$ ./venv3.8/bin/rcmpy variant -h + +usage: rcmpy variant [-h] variant + +positional arguments: + variant new variant to use + +optional arguments: + -h, --help show this help message and exit + +``` + # Internal Dependency Graph A coarse view of the internal structure and scale of diff --git a/im/pydeps.svg b/im/pydeps.svg index ba98f47..e90787c 100644 --- a/im/pydeps.svg +++ b/im/pydeps.svg @@ -4,611 +4,653 @@ - - + + G - + rcmpy___main__ - -rcmpy.__main__ + +rcmpy.__main__ rcmpy_app - -rcmpy.app + +rcmpy.app rcmpy_entry - -rcmpy.entry + +rcmpy.entry rcmpy_app->rcmpy_entry - - + + rcmpy_commands - -rcmpy.commands + +rcmpy.commands rcmpy_commands->rcmpy_app - - + + rcmpy_commands_all - -rcmpy. -commands. -all + +rcmpy. +commands. +all rcmpy_commands_all->rcmpy_app - - - + rcmpy_commands_apply - -rcmpy. -commands. -apply + +rcmpy. +commands. +apply rcmpy_commands_apply->rcmpy_commands_all - - + + rcmpy_commands_use - -rcmpy. -commands. -use + +rcmpy. +commands. +use rcmpy_commands_use->rcmpy_commands_all - - + + rcmpy_commands_variant - -rcmpy. -commands. -variant + +rcmpy. +commands. +variant rcmpy_commands_variant->rcmpy_commands_all - - + + rcmpy_config - -rcmpy.config + +rcmpy.config - + + +rcmpy_environment + +rcmpy. +environment + + -rcmpy_config->rcmpy_commands_apply - +rcmpy_config->rcmpy_environment + + rcmpy_entry->rcmpy___main__ - - + + + + + +rcmpy_environment->rcmpy_commands_apply + + + - + rcmpy_paths - -rcmpy.paths + +rcmpy.paths - + rcmpy_paths->rcmpy_commands_use - - + - + rcmpy_state - -rcmpy.state + +rcmpy.state - + rcmpy_paths->rcmpy_state - - + + - + rcmpy_schemas - -rcmpy.schemas + +rcmpy.schemas - + rcmpy_schemas->rcmpy_config - - + + - -rcmpy_schemas->rcmpy_state - - - - -rcmpy_state->rcmpy_commands_apply - - - +rcmpy_schemas->rcmpy_state + + rcmpy_state->rcmpy_commands_use - - - + + + rcmpy_state->rcmpy_commands_variant - - + + + + + + +rcmpy_state->rcmpy_environment + + - + rcmpy_xdg - -rcmpy.xdg + +rcmpy.xdg - + rcmpy_xdg->rcmpy_paths - - + + - + vcorelib - -vcorelib + +vcorelib - + vcorelib->rcmpy_app - + - + vcorelib->rcmpy_commands_all - - + + - + vcorelib->rcmpy_commands_apply - - - - + - + vcorelib->rcmpy_commands_use - + + + - + vcorelib->rcmpy_commands_variant - - + + - + vcorelib->rcmpy_config - - + + + + + +vcorelib->rcmpy_environment + + + - + vcorelib->rcmpy_paths - - + + - + vcorelib->rcmpy_schemas - - + + + - + vcorelib->rcmpy_state - - - - + + + + + - + vcorelib->rcmpy_xdg - - + + - + vcorelib_args - -vcorelib.args + +vcorelib.args - + vcorelib_args->rcmpy_app - - + + + + - + vcorelib_args->rcmpy_commands_all - - - + + - + vcorelib_args->rcmpy_commands_apply - - + + + + - + vcorelib_args->rcmpy_commands_use - - + + - + vcorelib_args->rcmpy_commands_variant - - - + + - + vcorelib_dict - -vcorelib.dict + +vcorelib.dict - + vcorelib_dict->rcmpy_config - - - - - - - + + + - + vcorelib_dict->rcmpy_paths - - + + - + vcorelib_dict->rcmpy_schemas - - - - + + + - + vcorelib_dict->rcmpy_state - - + - + vcorelib_io - -vcorelib.io + +vcorelib.io - + vcorelib_dict->vcorelib_io - - + - + vcorelib_io_types - -vcorelib. -io. -types + +vcorelib. +io. +types - + vcorelib_dict->vcorelib_io_types - - + + + - + vcorelib_dict_cache - -vcorelib. -dict. -cache + +vcorelib. +dict. +cache - + vcorelib_dict_cache->rcmpy_state - - + - + vcorelib_dict_codec - -vcorelib. -dict. -codec + +vcorelib. +dict. +codec - + vcorelib_dict_codec->rcmpy_config - + + - + vcorelib_dict_codec->rcmpy_schemas - + + - - -vcorelib_io->rcmpy_commands_apply - + + +vcorelib_io->rcmpy_environment + + - + vcorelib_io->rcmpy_state - - - + + + - + vcorelib_io->vcorelib_dict_cache - - + + + - + vcorelib_io->vcorelib_dict_codec - + - + vcorelib_schemas - -vcorelib. -schemas + +vcorelib. +schemas - + vcorelib_io->vcorelib_schemas - - - - + + + - + vcorelib_schemas_base - -vcorelib. -schemas. -base + +vcorelib. +schemas. +base - + vcorelib_io->vcorelib_schemas_base - - + + + - + vcorelib_schemas_json - -vcorelib. -schemas. -json + +vcorelib. +schemas. +json - + vcorelib_io->vcorelib_schemas_json - - - + + - - -vcorelib_io_types->rcmpy_commands_apply - - - - - + + +vcorelib_io_types->rcmpy_environment + + - + vcorelib_io_types->rcmpy_state - - + + + - + vcorelib_io_types->vcorelib_dict_cache - - + - + vcorelib_io_types->vcorelib_dict_codec - - - - + + - + vcorelib_io_types->vcorelib_io - - + + - + vcorelib_io_types->vcorelib_schemas - - + + - + vcorelib_io_types->vcorelib_schemas_base - - - + + - + vcorelib_io_types->vcorelib_schemas_json - + + + + + + +vcorelib_logging + +vcorelib. +logging + + + +vcorelib_logging->rcmpy_environment + - + vcorelib_paths - -vcorelib.paths + +vcorelib.paths + + + +vcorelib_paths->rcmpy_environment + + + + + + + - + vcorelib_paths->rcmpy_state - - + + - + vcorelib_paths->rcmpy_xdg - - - + + - + vcorelib_paths->vcorelib_dict_cache - - - + - + vcorelib_paths->vcorelib_dict_codec - - + + + + - + vcorelib_paths->vcorelib_io - - - + + + - + vcorelib_paths->vcorelib_io_types - - - + + - + vcorelib_paths->vcorelib_schemas_base - - + + - + vcorelib_paths->vcorelib_schemas_json - + + + + - + vcorelib_schemas->rcmpy_schemas - + + + + - + vcorelib_schemas->vcorelib_dict_codec - + + + - + vcorelib_schemas_base->rcmpy_schemas - - + + - + vcorelib_schemas_base->vcorelib_dict_codec - - + - + vcorelib_schemas_base->vcorelib_schemas - - + + - + vcorelib_schemas_base->vcorelib_schemas_json - - + + - + vcorelib_schemas_json->rcmpy_schemas - + diff --git a/local/configs/python.yaml b/local/configs/python.yaml index f490574..ebd8df9 100644 --- a/local/configs/python.yaml +++ b/local/configs/python.yaml @@ -3,7 +3,7 @@ author_info: name: Vaughn Kottler email: vaughnkottler@gmail.com username: vkottler -versions: ["3.7", "3.8", "3.9", "3.10"] +versions: ["3.7", "3.8", "3.9", "3.10", "3.11"] systems: - macos-latest diff --git a/local/includes/sub_commands.yaml b/local/includes/sub_commands.yaml new file mode 100644 index 0000000..42aac4e --- /dev/null +++ b/local/includes/sub_commands.yaml @@ -0,0 +1,15 @@ +# yamllint disable-file +--- +default_dirs: false + +commands: +{% for command in ["apply", "use", "variant"] %} + - name: help-{{command}} + command: "./venv{{python_version}}/bin/{{entry}}" + force: true + arguments: + - {{command}} + - "-h" + dependencies: + - commands-install-local +{% endfor %} diff --git a/local/templates/README.md.j2 b/local/templates/README.md.j2 index e2dda53..78835db 100644 --- a/local/templates/README.md.j2 +++ b/local/templates/README.md.j2 @@ -1,4 +1,39 @@ {{python_readme_header_md}} + +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 information that needs to persist between command invocations +in a `{{package["name"]}}` sub-directory in 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 `{{package["name"]}}/default` sub-directory in the +user-config directory controlled by `XDG_CONFIG_HOME` (or the default: +`$HOME/.config`). {% if "help" in global %} # Command-line Options @@ -10,4 +45,17 @@ $ {{" ".join(help["args"])}} ``` {% endif %} +## Sub-command Options +{% for command in package["commands"] %} + +### `{{command["name"]}}` +{% set help_data = global["help-" + command["name"]] %} + +``` +$ {{" ".join(help_data["args"])}} + +{{help_data["stdout"]}} +``` +{% endfor %} + {{python_readme_dep_graph_md}} diff --git a/local/templates/data_repository.md.j2 b/local/templates/data_repository.md.j2 new file mode 100644 index 0000000..2d0997b --- /dev/null +++ b/local/templates/data_repository.md.j2 @@ -0,0 +1,5 @@ +# Data Repository + +([back](../README.md#getting-started)) + +TODO. diff --git a/manifest.yaml b/manifest.yaml index dec08aa..104755d 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -10,6 +10,7 @@ includes: - config/includes/python.yaml - config/includes/license.yaml - config/includes/funding.yaml + - local/includes/sub_commands.yaml templates: - local/templates @@ -29,6 +30,14 @@ renders: - renders-python_readme_header.md - renders-python_readme_dep_graph.md - commands-help + - commands-help-apply + - commands-help-use + - commands-help-variant + + - name: data_repository.md + output_dir: "md" + dependencies: + - compiles-local - name: app.py output_dir: "{{project}}" @@ -47,5 +56,6 @@ groups: - groups-license - groups-funding - renders-README.md + - renders-data_repository.md - renders-app.py - renders-all.py diff --git a/md/data_repository.md b/md/data_repository.md new file mode 100644 index 0000000..1c10c66 --- /dev/null +++ b/md/data_repository.md @@ -0,0 +1,13 @@ + + +# Data Repository + +([back](../README.md#getting-started)) + +TODO. diff --git a/pyproject.toml b/pyproject.toml index 33f8c23..2e991c1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,7 @@ classifiers = [ "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", "Operating System :: Microsoft :: Windows", "Operating System :: MacOS", "Operating System :: POSIX :: Linux", diff --git a/setup.py b/setup.py index f3fc7ee..3103347 100644 --- a/setup.py +++ b/setup.py @@ -1,7 +1,7 @@ # ===================================== # generator=datazen # version=3.1.0 -# hash=416bc5bcfd6143aac0a78a91308857db +# hash=dc0d9f835ecbdaf7ba7d62dc617acb8d # ===================================== """ @@ -32,6 +32,7 @@ "3.8", "3.9", "3.10", + "3.11", ], } setup(