diff --git a/.auxiliary/configuration/copier-answers.yaml b/.auxiliary/configuration/copier-answers.yaml index a81407c..982385c 100644 --- a/.auxiliary/configuration/copier-answers.yaml +++ b/.auxiliary/configuration/copier-answers.yaml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: v1.4 +_commit: v1.6 _src_path: gh:emcd/python-project-common author_email: emcd@users.noreply.github.com author_name: Eric McDonald diff --git a/.editorconfig b/.editorconfig index cbbfde3..040fb65 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,19 +15,19 @@ trim_trailing_whitespace = true [*.md] max_line_length = 79 -[*.py,*.py.jinja] +[*.{py,py.jinja}] max_line_length = 79 insert_final_newline = true -[*.rs,*.rs.jinja] +[*.{rs,rs.jinja}] max_line_length = 79 insert_final_newline = true -[*.rst,*.rst.jinja] +[*.{rst,rst.jinja}] indent_size = 2 max_line_length = 79 -[*.toml,*.toml.jinja] +[*.{toml,toml.jinja}] indent_size = 2 [*.yaml] diff --git a/.github/workflows/releaser.yaml b/.github/workflows/releaser.yaml index d9112ca..4cb2cad 100644 --- a/.github/workflows/releaser.yaml +++ b/.github/workflows/releaser.yaml @@ -24,7 +24,7 @@ jobs: test: needs: [initialize] - uses: emcd/python-project-common/.github/workflows/xrepo--tester.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--tester.yaml@v1.6 with: matrix-exclusions: '${{ needs.initialize.outputs.matrix-exclusions }}' platforms: '${{ needs.initialize.outputs.platforms }}' @@ -34,7 +34,7 @@ jobs: report: needs: [initialize, test] - uses: emcd/python-project-common/.github/workflows/xrepo--reporter.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--reporter.yaml@v1.6 with: python-version: '${{ fromJSON(needs.initialize.outputs.python-versions)[0] }}' @@ -44,14 +44,14 @@ jobs: contents: write id-token: write pages: write - uses: emcd/python-project-common/.github/workflows/xrepo--documenter.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--documenter.yaml@v1.6 with: include-reports: true python-version: '${{ fromJSON(needs.initialize.outputs.python-versions)[0] }}' package: needs: [initialize, docsgen] - uses: emcd/python-project-common/.github/workflows/xrepo--packager.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--packager.yaml@v1.6 with: artifacts-path: '.auxiliary/artifacts/hatch-build' # TODO: Use environment. python-version: '${{ fromJSON(needs.initialize.outputs.python-versions)[0] }}' diff --git a/.github/workflows/tester.yaml b/.github/workflows/tester.yaml index 16c6867..3de4192 100644 --- a/.github/workflows/tester.yaml +++ b/.github/workflows/tester.yaml @@ -14,7 +14,7 @@ jobs: test: needs: [initialize] - uses: emcd/python-project-common/.github/workflows/xrepo--tester.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--tester.yaml@v1.6 with: matrix-exclusions: '${{ needs.initialize.outputs.matrix-exclusions }}' platforms: '${{ needs.initialize.outputs.platforms }}' @@ -24,6 +24,6 @@ jobs: report: needs: [initialize, test] - uses: emcd/python-project-common/.github/workflows/xrepo--reporter.yaml@v1.4 + uses: emcd/python-project-common/.github/workflows/xrepo--reporter.yaml@v1.6 with: python-version: '${{ fromJSON(needs.initialize.outputs.python-versions)[0] }}' diff --git a/documentation/sphinx/conf.py b/documentation/sphinx/conf.py index f8cb08a..325fdc6 100644 --- a/documentation/sphinx/conf.py +++ b/documentation/sphinx/conf.py @@ -78,6 +78,8 @@ def _import_version( ): ( 'py:class', "v, remove specified key and return the corresponding value." ), # Type annotation weirdnesses. + ( 'py:class', "Doc" ), + ( 'py:class', "types.Annotated" ), ( 'py:class', "typing_extensions.Any" ), ] diff --git a/documentation/sphinx/development/practices.rst b/documentation/sphinx/development/practices.rst index 961db3a..318d0dd 100644 --- a/documentation/sphinx/development/practices.rst +++ b/documentation/sphinx/development/practices.rst @@ -31,7 +31,7 @@ Documentation or which attempt to provide function docstrings in the style of Google, NumPy, Sphinx, etc..., will be rejected. -.. todo:: Rust Documentation + * Use long option names, whenever possible, in command line examples. Readers, who are unfamiliar with a command, should not have to look up the meanings of @@ -51,7 +51,7 @@ Exceptional Conditions ``from`` original exception or raise a new exception with original exception as the ``__context__``. Or properly handle the exception. -.. todo:: Rust Panics + Imports =============================================================================== diff --git a/documentation/sphinx/development/releases.rst b/documentation/sphinx/development/releases.rst index e2aed52..c2814d0 100644 --- a/documentation/sphinx/development/releases.rst +++ b/documentation/sphinx/development/releases.rst @@ -129,3 +129,76 @@ Postrelease Patch 10. Cherry-pick patch and Towncrier commits back to ``master`` branch, resolving conflicts as necessary. + +Changelog Entries +=============================================================================== + +The project uses `Towncrier `_ to manage its +changelog. When making changes that should be noted in the changelog, add a +file ("fragment") to the ``documentation/towncrier`` directory with of +``..rst``, for changes with a Github issue, or +``+.<type>.rst``, for changes without an associated issue number. + +The entries will be collected and organized when a release is made, as +described in the release process sections above. + +Available Types +------------------------------------------------------------------------------- + +* ``bugfix``: For bug fixes +* ``docs``: For documentation improvements +* ``feature``: For new features +* ``platform``: For changes to supported platforms +* ``removal``: For deprecations and removals + +Format +------------------------------------------------------------------------------- + +The file should contain a concise description of the change written in present +tense. For example: + +.. code-block:: rst + :caption: documentation/towncrier/+immutable-modules.feature.rst + + Add support for immutable module reclassification. + +The description should: + +* Start with a capital letter +* End with a period +* Use present tense (e.g., "Add", "Fix", "Update") +* Focus on the what and why, not the how +* Be understandable by users, not just developers + +Examples +------------------------------------------------------------------------------- + +Bug Fix: + .. code-block:: rst + :caption: documentation/towncrier/456.bugfix.rst + + Fix attribute visibility in immutable modules. + +Documentation: + .. code-block:: rst + :caption: documentation/towncrier/457.docs.rst + + Improve release process documentation with Towncrier details. + +Feature: + .. code-block:: rst + :caption: documentation/towncrier/458.feature.rst + + Add recursive module reclassification support. + +Platform: + .. code-block:: rst + :caption: documentation/towncrier/459.platform.rst + + Add support for Python 3.13. + +Removal: + .. code-block:: rst + :caption: documentation/towncrier/460.removal.rst + + Remove deprecated ``make_immutable`` function. diff --git a/documentation/sphinx/development/style.rst b/documentation/sphinx/development/style.rst index 344e734..7914463 100644 --- a/documentation/sphinx/development/style.rst +++ b/documentation/sphinx/development/style.rst @@ -48,7 +48,7 @@ Code Style style other than the project code style, will be rejected. -.. todo:: Rust Guidance + Specific Preferences @@ -186,9 +186,8 @@ the last element unless the collection has a trailing comma:: if is_valid( value ) ] # Multi-line conditional statements - if ( - validate_input( data, strict = True ) - and process_ready( ) + if ( validate_input( data, strict = True ) + and process_ready( ) ): process( data ) diff --git a/pyproject.toml b/pyproject.toml index 116d09d..79147ae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -288,7 +288,7 @@ disable = [ ] # TODO: Latest 'per-file-ignores' code may supports dicts and lists in addition to strings. per-file-ignores = ''' - /tests/:attribute-defined-outside-init,magic-value-comparison,missing-class-docstring,missing-function-docstring,protected-access,unexpected-keyword-arg + /tests/:attribute-defined-outside-init,comparison-with-itself,magic-value-comparison,missing-class-docstring,missing-function-docstring,protected-access,singleton-comparison,superfluous-parens,unexpected-keyword-arg __init__\.py:unused-import ''' # Note: Paths are regexes. [tool.pylint.refactoring] diff --git a/sources/emcd_projects/__init__.py b/sources/emcd_projects/__init__.py index 6a08a87..ec60f29 100644 --- a/sources/emcd_projects/__init__.py +++ b/sources/emcd_projects/__init__.py @@ -25,7 +25,7 @@ from . import exceptions -__version__ = '1.0a0' +__version__ = '1.7a0' # TODO: Reclassify package modules as immutable and concealed. diff --git a/sources/emcd_projects/exceptions.py b/sources/emcd_projects/exceptions.py index 911edee..79e7c7b 100644 --- a/sources/emcd_projects/exceptions.py +++ b/sources/emcd_projects/exceptions.py @@ -25,11 +25,14 @@ ''' +from . import __ + + class Omniexception( BaseException ): ''' Base for all exceptions raised by package API. ''' - # TODO: Class and instance attribute immutability. + # TODO: Class and instance attribute concealment and immutability. - _attribute_visibility_includes_: frozenset[ str ] = ( + _attribute_visibility_includes_: __.cabc.Collection[ str ] = ( frozenset( ( '__cause__', '__context__', ) ) )