ycleptic 2.0.2__tar.gz → 2.0.4__tar.gz

ycleptic-2.0.4/.github/workflows/release.yaml

@@ -0,0 +1,91 @@
+name: Release & Upload to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install package and test dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/
+
+      - name: Install Hatch
+        run: python -m pip install --upgrade hatch
+
+      - name: Verify tag matches pyproject version and CHANGELOG
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER="$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')"
+          echo "Tag version:     $TAG"
+          echo "Project version: $VER"
+          test "$TAG" = "$VER" || { echo "ERROR: tag $TAG != pyproject version $VER"; exit 1; }
+          grep -q "^## \[$VER\]" CHANGELOG.md || { echo "ERROR: no CHANGELOG entry for $VER"; exit 1; }
+
+      - name: Clean previous builds
+        run: rm -rf dist/
+
+      - name: Build the package with Hatch
+        run: hatch build
+
+      - name: Extract release notes from CHANGELOG.md
+        run: |
+          echo 'RELEASE_BODY<<EOF' >> $GITHUB_ENV
+          awk '
+            BEGIN {found=0; capture=0}
+            /^## \[Unreleased\]/ {next}
+            /^## \[/ {
+              if (found) exit;
+              found = 1;
+              capture = 1;
+              next
+            }
+            /^## / {capture=0}
+            capture {print}
+          ' CHANGELOG.md >> $GITHUB_ENV
+          echo 'EOF' >> $GITHUB_ENV
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          body: ${{ env.RELEASE_BODY }}
+          files: |
+            dist/*.tar.gz
+            dist/*.whl
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Trigger ReadTheDocs build
+        run: |
+          curl -X POST \
+            -H "Authorization: Token ${{ secrets.RTD_SECRET }}" \
+            https://readthedocs.org/api/v3/projects/ycleptic/versions/latest/builds/
+          curl -X POST \
+            -H "Authorization: Token ${{ secrets.RTD_SECRET }}" \
+            https://readthedocs.org/api/v3/projects/ycleptic/versions/${{ github.ref_name }}/builds/

{ycleptic-2.0.2 → ycleptic-2.0.4}/.github/workflows/update_docs_only.yaml

@@ -22,4 +22,4 @@ jobs:
         run: |
           curl -X POST \
             -H "Authorization: Token ${{ secrets.RTD_SECRET }}" \
-            https://readthedocs.org/api/v3/projects/pidibble/versions/latest/builds/
+            https://readthedocs.org/api/v3/projects/ycleptic/versions/latest/builds/

{ycleptic-2.0.2 → ycleptic-2.0.4}/.gitignore

@@ -78,6 +78,14 @@ instance/
 docs/_build/
 docs/source/_build
 
+# Test-generated output files
+tests/test_set/example1.yaml
+tests/test_set/user-dump.yaml
+tests/test_set/console-out.txt
+tests/test_set/ydoc.rst
+tests/test_set/ydoc/
+tests/test_set/rcfile.yaml
+
 # PyBuilder
 target/
 

{ycleptic-2.0.2 → ycleptic-2.0.4}/.readthedocs.yaml

@@ -1,12 +1,14 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.12"
   jobs:
     pre_build:
+      - rm -rf docs/source/api/
       - sphinx-apidoc -f -M -e --implicit-namespaces --tocfile API -o docs/source/api ycleptic/
+      - yclept make-doc ycleptic/resources/example_base.yaml --root docs/source/example_config --footer-style raw-html
 
 sphinx:
   configuration: docs/source/conf.py

ycleptic-2.0.4/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+---
+
+## [2.0.4] - 2026-05-01
+
+### Fixed
+- RTD workflow was triggering docs builds on wrong project (`pidibble` instead of `ycleptic`)
+- README Contributing section linked to a different repository's fork page
+- `test_makedoc` expected string was stale (`"Single-valued parameters:"` → `"Single-valued attributes:"`)
+- Bare `except:` clauses in `walkers.py` narrowed to `except ValueError:`
+- Mutable default arguments `userdict={}` and `new_data={}` in `Yclept` replaced with `None`-defaulted parameters
+- `exit(0)` in `_endhelp` replaced with `sys.exit(0)`
+- `D["name"]` in `walkers.dwalk` raised `KeyError` at the root config level; replaced with `D.get("name", "root")`
+- `type(x) == list/dict` identity comparisons replaced with `isinstance()` throughout
+
+### Changed
+- `make-doc` subcommand and `make_doctree` now accept a path for `--root` (e.g. `docs/source/config_ref`), so the command can be run from the project root without a prior `cd docs/source`; `makedoc.py` refactored from `os.chdir()` traversal to `pathlib.Path` throughout
+- Debug `print()` calls in `makedoc.py` and `conf.py` converted to `logging.debug()` and removed respectively
+- `docs/requirements.txt` de-duplicated and dead dependencies (`recommonmark`, `commonmark`, `alabaster`, `sphinx-rtd-theme`, `pillow`, `mock`) removed
+- `cli.py` `config_help` now has a safe fallback for `write_func` when an unrecognized value is passed
+
+### Added
+- `from __future__ import annotations` added to all source modules for Python 3.7/3.8 annotation compatibility
+- `logging.NullHandler()` registered in package `__init__` per library logging best practices
+- `pytest` step added to release workflow before PyPI publish
+- Test suite expanded from 9 to 29 tests; `tearDown` added for automatic cleanup of generated files
+- Test-generated output files added to `.gitignore`
+- This changelog
+
+---
+
+## [2.0.3] - 2025-09-04
+
+- Renamed `directive` to `attribute` throughout codebase and documentation
+
+## [2.0.2] - 2025-09-04
+
+- Refactored `make_doc` internal path-handling logic
+
+## [2.0.1] - 2025-08-22
+
+- Documentation updates
+
+## [1.9.0] - 2025-08-18
+
+- Added `update_user` method to `Yclept`
+
+## [1.8.1] - 2025-08-04
+
+- Fixed faulty special update of dict-like values with defaults
+
+## [1.8.0] - 2025-07-29
+
+- More informative error messages via `raise_clean`
+
+## [1.7.0] - 2025-07-16
+
+- Restructured code-base and expanded documentation
+
+## [1.6.2] - 2025-06-18
+
+- Added `--footer-style` argument to `make-doc` CLI command
+
+## [1.6.1] - 2025-06-18
+
+- Version and configuration housekeeping
+
+## [1.6.0] - 2025-06-18
+
+- Internal release
+
+## [1.5.0] - 2025-06-15
+
+- Added `example` subfield to `docs` attribute specification
+
+## [1.4.1] - 2025-05-21
+
+- Enabled `case_sensitive` boolean for all `str`-type attributes
+
+## [1.4.0] - 2025-05-21
+
+- Initial implementation of `case_sensitive` attribute
+
+## [1.3.0] - 2025-04-01
+
+- `Yclept.__init__` now accepts a `userdict` dict in addition to a file path
+
+## [1.2.0] - 2025-02-10
+
+- `make-doc` subcommand now emits RST cross-reference links at the top of every generated RST file
+
+## [1.1.0]
+
+- Fixed: default values now shown for dict-type attributes in `console_help`
+- Fixed: `choices` validation now works with integer choices
+
+## [1.0.7]
+
+- Fixed bad string in doc builder
+
+## [1.0.6]
+
+- Implemented interactive help mode
+- Added `config-help` CLI subcommand
+- Added `make-doc` CLI subcommand
+
+## [1.0.5]
+
+- Added support for a user dotfile/rcfile
+
+## [1.0.4]
+
+- Added `**kwargs` to `console_help` to allow `write_func` override
+
+## [1.0.3.3]
+
+- Fixed spurious output
+
+## [1.0.3.2]
+
+- Fixed version detection bug
+
+## [1.0.2]
+
+- Updated documentation; added version detection
+
+## [1.0.1]
+
+- Added example base config resource
+
+## [1.0.0]
+
+- Initial release

{ycleptic-2.0.2 → ycleptic-2.0.4}/PKG-INFO

@@ -1,17 +1,45 @@
 Metadata-Version: 2.4
 Name: ycleptic
-Version: 2.0.2
+Version: 2.0.4
 Summary: A YAML-format configuration generator
 Project-URL: Source, https://github.com/cameronabrams/ycleptic
 Project-URL: Documentation, https://ycleptic.readthedocs.io/en/latest/
 Project-URL: Bug Tracker, https://github.com/cameronabrams/ycleptic/issues
 Author-email: Cameron F Abrams <cfa22@drexel.edu>
+License: MIT License
+        
+        Copyright (c) 2022 Cameron Abrams
+        
+        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.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.7
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
 Requires-Dist: pyyaml>=6
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
 
 # Ycleptic
@@ -34,49 +62,8 @@ pip install ycleptic
 Once installed, the developer has access to the ``Yclept`` class.
 
 ## Release History
-* 2.0.2
-    * refactored to change `directive` to `attribute` throughout
-* 1.9.0
-    * new `update_user` method
-* 1.8.1
-    * fixed faulty special update of dict-like values with defaults
-* 1.8.0
-    * more informative error messages via `raise_clean`
-* 1.7.0
-    * Restructured code-base and expanded documentation
-* 1.6.2
-    * `footer-style` argument added to `make-docs`
-* 1.5.0
-    * `example` subfield in `docs` directive enabled
-* 1.4.1
-    * `case_sensitive` boolean attribute enabled for all `str`-types
-* 1.3.0
-    * `__init__` optionally accepts a dict instead of only a file name
-* 1.2.0
-    * `make-doc` subcommand upgraded to put RST links at the top of every RST file
-* 1.1.0
-    * bugfix: shows default values for any dict-type parameters
-    * bugfix: `choices` in interactive help did not work with integer choices
-* 1.0.7
-    * bugfix: bad string in doc builder
-* 1.0.6
-    * interactive mode implemented
-    * `config-help` subcommand added
-    * `make-doc` subcommand added
-* 1.0.5
-    * added support for a user dotfile/rcfile
-* 1.0.4
-    * added `**kwargs` to `console_help` to allow override of `print`
-* 1.0.3.3
-    * fixed spurious output
-* 1.0.3.2
-    * fixed version detection bug
-* 1.0.2
-    * Updated documentation; added version detection
-* 1.0.1
-    * Include example base config
-* 1.0.0
-    * Initial version
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
 ## Meta
 
@@ -90,7 +77,7 @@ Distributed under the MIT license. See ``LICENSE`` for more information.
 
 ## Contributing
 
-1. Fork it (<https://github.com/AbramsGroup/HTPolyNet/fork>)
+1. Fork it (<https://github.com/cameronabrams/ycleptic/fork>)
 2. Create your feature branch (`git checkout -b feature/fooBar`)
 3. Commit your changes (`git commit -am 'Add some fooBar'`)
 4. Push to the branch (`git push origin feature/fooBar`)

ycleptic-2.0.4/README.md

@@ -0,0 +1,41 @@
+# Ycleptic
+> YAML configuration generator
+
+YAML is a popular markup language for input files, with its easy syntax and clear
+mapping to lists and dicts.  Ycleptic allows a developer to specify all keys, datatypes,
+default values, choice restrictions, and other features of YAML-format input 
+files for use in their own apps. This makes the specification of input file syntax on top 
+of YAML for any particular application a bit easier than just using pure YAML.  In addition,
+ycleptic can also automatically build the RST/Sphinx doctree for your app's configuration
+file.
+
+## Installation
+
+```bash
+pip install ycleptic
+```
+
+Once installed, the developer has access to the ``Yclept`` class.
+
+## Release History
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+## Meta
+
+Cameron F. Abrams – cfa22@drexel.edu
+
+Distributed under the MIT license. See ``LICENSE`` for more information.
+
+[https://github.com/cameronabrams](https://github.com/cameronabrams/)
+
+[https://github.com/AbramsGroup](https://github.com/AbramsGroup/)
+
+## Contributing
+
+1. Fork it (<https://github.com/cameronabrams/ycleptic/fork>)
+2. Create your feature branch (`git checkout -b feature/fooBar`)
+3. Commit your changes (`git commit -am 'Add some fooBar'`)
+4. Push to the branch (`git push origin feature/fooBar`)
+5. Create a new Pull Request
+

ycleptic-2.0.4/docs/requirements.txt

@@ -0,0 +1,8 @@
+sphinx
+furo
+myst-parser
+sphinx-copybutton
+sphinxcontrib-mermaid
+readthedocs-sphinx-ext<2.3
+pyyaml
+ycleptic

ycleptic-2.0.4/docs/source/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+:heading-offset: 1
+```

{ycleptic-2.0.2 → ycleptic-2.0.4}/docs/source/conf.py

@@ -21,6 +21,7 @@ extensions = [
     'sphinxcontrib.mermaid',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    'myst_parser',
 ]
 
 autosummary_generate = True  # Enable autosummary tables
@@ -79,5 +80,4 @@ epub_show_urls = 'footnote'
 mermaid_params = ['--theme', 'dark', '--width', '600']
 
 def setup(app):
-    print("✅ Setting up custom directives...") 
     app.add_css_file("css/custom.css")

{ycleptic-2.0.2 → ycleptic-2.0.4}/docs/source/index.rst

@@ -19,9 +19,10 @@ Contents
 
 .. toctree::
    :maxdepth: 1
-   
+
    about
    installation
    usage
    API <api/API>
+   changelog
 

{ycleptic-2.0.2 → ycleptic-2.0.4}/docs/source/usage/class.rst

@@ -3,9 +3,9 @@
 ``Yclept`` Class
 ====================
 
-Installation of Ycleptic gives access to the :class:`Yclept` class.
+Installation of Ycleptic gives access to the :class:`ycleptic.yclept.Yclept` class.
 
-The :class:`Yclept` class is meant to be used inside any Python package where the developer
+The :class:`ycleptic.yclept.Yclept` class is meant to be used inside any Python package where the developer
 wants to specify the allowed formats, expected values, default values, required
 values, etc., of a YAML-format configuration file for the developer's app.
 
@@ -30,7 +30,7 @@ To use ``ycleptic`` in your app, you must create a base configuration file that
 
 ``base.yaml`` is a base configuration file. More about that file in a moment.
 
-You then might like to create a "config" class for your package that inherits :class:`Yclept`, and initialize it with your base config and a user config. For example:
+You then might like to create a "config" class for your package that inherits :class:`ycleptic.yclept.Yclept`, and initialize it with your base config and a user config. For example:
 
 .. code-block:: python
 

ycleptic-2.0.4/docs/source/usage/yclept_makedoc.rst

@@ -0,0 +1,92 @@
+.. _usage_yclept_makedoc:
+
+``yclept make-doc``
+===================
+
+The ``yclept make-doc`` command generates a Sphinx RST document tree from your
+base configuration file.
+
+Basic usage
+-----------
+
+Given a package structured like this:
+
+.. code-block:: text
+
+   myproject/
+   ├── mypackage/
+   │   ├── data/
+   │   │   ├── base.yaml
+   │   │   └── __init__.py
+   │   └── __init__.py
+   ├── docs/
+   │   └── source/
+   │       └── intro.rst
+   └── pyproject.toml
+
+Run ``yclept make-doc`` from the project root, passing the full path to both
+the base config file and the desired output location:
+
+.. code-block:: console
+
+   $ yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref
+
+This writes ``docs/source/config_ref.rst`` and populates
+``docs/source/config_ref/`` with one RST file per attribute, mirroring the
+nesting of your base config.  No ``cd`` into ``docs/source`` is required.
+
+Then add ``config_ref`` to your Sphinx ``toctree``:
+
+.. code-block:: rst
+
+   .. toctree::
+      :maxdepth: 1
+
+      config_ref
+
+For a live example of the output, see
+`pestifer's configuration reference <https://pestifer.readthedocs.io/en/latest/config_ref.html>`_,
+which is generated entirely by ``yclept make-doc``.
+
+ReadTheDocs integration
+-----------------------
+
+To regenerate the doc tree on every RTD build, add the command to the
+``pre_build`` jobs in ``.readthedocs.yaml``:
+
+.. code-block:: yaml
+
+   build:
+     os: ubuntu-24.04
+     tools:
+       python: "3.12"
+     jobs:
+       pre_build:
+         - yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref --footer-style raw-html
+
+Footer styles
+-------------
+
+Each generated RST file ends with a footer whose appearance is controlled by
+``--footer-style``.  The available styles are:
+
+``paragraph`` (default)
+   A horizontal rule followed by a plain paragraph.
+
+   .. code-block:: rst
+
+      ----
+
+      This page was automatically generated by **ycleptic** v2.0.3 on 2025-09-04.
+
+``comment``
+   An RST comment — present in the source but invisible in the rendered output.
+
+``note``
+   A Sphinx ``.. note::`` directive.
+
+``rubric``
+   A ``.. rubric::`` heading outside the normal document hierarchy.
+
+``raw-html``
+   A ``.. raw:: html`` block, useful for styled footers with CSS classes.

ycleptic-2.0.4/docs/source/usage.rst

@@ -0,0 +1,15 @@
+Usage
+=====
+
+``Ycleptic`` primarily exposes the :class:`ycleptic.yclept.Yclept` class to inherit in your own applications.  It also has a command-line interface with two subcommands: ``yclept config-help`` and ``yclept make-doc``.  The former provides interactive help for the configuration file, and the latter generates documentation from the base configuration file.
+
+.. toctree:: 
+   :maxdepth: 1
+
+   usage/class
+   usage/the_base_config
+   usage/the_user_config
+   usage/interactive_help
+   usage/resource_file
+   usage/yclept_config-help
+   usage/yclept_makedoc

{ycleptic-2.0.2 → ycleptic-2.0.4}/pyproject.toml

@@ -3,21 +3,30 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "ycleptic"
-version = "2.0.2"
+version = "2.0.4"
 authors = [
   { name="Cameron F Abrams", email="cfa22@drexel.edu" },
 ]
 description = "A YAML-format configuration generator"
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
 dependencies = [
     "pyyaml>=6"
 ]
+
+[project.optional-dependencies]
+test = ["pytest"]
 [project.scripts]
 yclept = "ycleptic.cli:cli"
 [project.urls]