PyPI - emcd-projects - Versions diffs - 1.23a0__tar.gz → 1.24__tar.gz - Mend

emcd-projects 1.23a0tar.gz → 1.24tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

{emcd_projects-1.23a0 → emcd_projects-1.24}/.gitignore RENAMED Viewed

@@ -1,9 +1,12 @@
 .env
+.gemini
+.mcp.json
 *.so
 .*.swp
 AGENTS.md
 CLAUDE.md
 CONVENTIONS.md
+GEMINI.md
 __pycache__/
 bugs/
 dist/

{emcd_projects-1.23a0 → emcd_projects-1.24}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: emcd-projects
-Version: 1.23a0
+Version: 1.24
 Summary: Project management utilities.
 Project-URL: Homepage, https://github.com/emcd/python-project-common
 Project-URL: Documentation, https://emcd.github.io/python-project-common

emcd_projects-1.24/data/templates/website.html.jinja ADDED Viewed

@@ -0,0 +1,103 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Available Releases</title>
+    <style>
+        table {
+            width: 100%;
+            border-collapse: collapse;
+        }
+        th, td {
+            padding: 8px;
+            text-align: left;
+            border-bottom: 1px solid #ddd;
+        }
+        th {
+            background-color: #f2f2f2;
+        }
+        tr:hover {
+            background-color: #f5f5f5;
+        }
+    </style>
+</head>
+<body>
+    <h1>Available Releases</h1>
+    {% if stable_dev_versions %}
+    <h2>Current Releases</h2>
+    <table>
+        <thead>
+            <tr>
+                <th>Version</th>
+                <th>Documentation</th>
+                <th>Coverage</th>
+            </tr>
+        </thead>
+        <tbody>
+        {% for version_label, attributes in stable_dev_versions.items() %}
+            <tr>
+                <td>{{ version_label }}</td>
+                <td>
+                {% if 'sphinx-html' in attributes %}
+                    {% if version_label.startswith('stable') %}
+                        <a href="stable/sphinx-html/index.html">Docs</a>
+                    {% elif version_label.startswith('development') %}
+                        <a href="development/sphinx-html/index.html">Docs</a>
+                    {% endif %}
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+                <td>
+                {% if 'coverage-pytest' in attributes %}
+                    {% if version_label.startswith('stable') %}
+                        <a href="stable/coverage-pytest/index.html">Coverage</a>
+                    {% elif version_label.startswith('development') %}
+                        <a href="development/coverage-pytest/index.html">Coverage</a>
+                    {% endif %}
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+            </tr>
+        {% endfor %}
+        </tbody>
+    </table>
+    <h2>All Releases</h2>
+    {% endif %}
+    <table>
+        <thead>
+            <tr>
+                <th>Version</th>
+                <th>Documentation</th>
+                <th>Coverage</th>
+            </tr>
+        </thead>
+        <tbody>
+        {% for version, attributes in versions.items() %}
+            <tr>
+                <td>{{ version }}</td>
+                <td>
+                {% if 'sphinx-html' in attributes %}
+                    <a href="{{ version }}/sphinx-html/index.html">Docs</a>
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+                <td>
+                {% if 'coverage-pytest' in attributes %}
+                    <a href="{{ version }}/coverage-pytest/index.html">Coverage</a>
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+            </tr>
+        {% endfor %}
+        </tbody>
+    </table>
+</body>
+</html>

{emcd_projects-1.23a0 → emcd_projects-1.24}/pyproject.toml RENAMED Viewed

@@ -111,9 +111,7 @@ description = ''' Development environment. '''
 dependencies = [
   'Jinja2',
   'coverage[toml]',
-  'emcd-projects',
   'furo',
-  'icecream-truck',
   'packaging',
   'pre-commit',
   'pyfakefs',

{emcd_projects-1.23a0 → emcd_projects-1.24}/sources/emcdproj/__/imports.py RENAMED Viewed

@@ -18,13 +18,11 @@
 #============================================================================#
-''' Common imports and type aliases used throughout the package. '''
+''' Common imports used throughout the package. '''
 # ruff: noqa: F401
-from __future__ import annotations
 import                      abc
 import collections.abc as   cabc
 import contextlib as        ctxl
@@ -33,6 +31,7 @@ import                      io
 import                      json
 import                      math
 import                      os
+import                      subprocess
 import                      shutil
 import                      sys
 import                      tempfile

{emcd_projects-1.23a0 → emcd_projects-1.24}/sources/emcdproj/__init__.py RENAMED Viewed

@@ -27,7 +27,7 @@ from . import exceptions
 # --- END: Injected by Copier ---
-__version__ = '1.23a0'
+__version__ = '1.24'
 def main( ):

{emcd_projects-1.23a0 → emcd_projects-1.24}/sources/emcdproj/cli.py RENAMED Viewed

@@ -21,8 +21,6 @@
 ''' Command-line interface. '''
-from __future__ import annotations
 from . import __
 from . import interfaces as _interfaces
 from . import template as _template

{emcd_projects-1.23a0 → emcd_projects-1.24}/sources/emcdproj/website.py RENAMED Viewed

@@ -19,8 +19,6 @@
 ''' Static website maintenance utilities for projects. '''
-# TODO: Support separate section for current documentation: stable, latest.
-# TODO? Separate coverage SVG files for each release.
 from __future__ import annotations
@@ -60,11 +58,15 @@ class SurveyCommand(
 ):
     ''' Surveys release versions published in static website. '''
+    use_extant: __.typx.Annotated[
+        bool,
+        __.typx.Doc( ''' Fetch publication branch and use tarball. ''' ),
+    ] = False
     async def __call__(
         self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
     ) -> None:
-        # TODO: Implement.
-        pass
+        survey( auxdata, use_extant = self.use_extant )
 class UpdateCommand(
@@ -78,10 +80,24 @@ class UpdateCommand(
         __.tyro.conf.Positional,
     ]
+    use_extant: __.typx.Annotated[
+        bool,
+        __.typx.Doc( ''' Fetch publication branch and use tarball. ''' ),
+    ] = False
+    production: __.typx.Annotated[
+        bool,
+        __.typx.Doc( ''' Update publication branch with new tarball.
+                     Implies --use-extant to prevent data loss. ''' ),
+    ] = False
     async def __call__(
         self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
     ) -> None:
-        update( auxdata, self.version )
+        update(
+            auxdata, self.version,
+            use_extant = self.use_extant,
+            production = self.production )
 class Locations( metaclass = __.ImmutableDataclass ):
@@ -129,11 +145,57 @@ class Locations( metaclass = __.ImmutableDataclass ):
             templates = templates )
+def survey(
+    auxdata: __.Globals, *,
+    project_anchor: __.Absential[ __.Path ] = __.absent,
+    use_extant: bool = False
+) -> None:
+    ''' Surveys release versions published in static website.
+        Lists all versions from the versions manifest, showing their
+        available documentation types and highlighting the latest version.
+    '''
+    locations = Locations.from_project_anchor( auxdata, project_anchor )
+    # Handle --use-extant flag: fetch publication branch and checkout tarball
+    if use_extant:
+        _fetch_publication_branch_and_tarball( locations )
+        # Extract the fetched tarball to view published versions
+        if locations.archive.is_file( ):
+            from tarfile import open as tarfile_open
+            if locations.website.is_dir( ):
+                __.shutil.rmtree( locations.website )
+            locations.website.mkdir( exist_ok = True, parents = True )
+            with tarfile_open( locations.archive, 'r:xz' ) as archive:
+                archive.extractall( path = locations.website ) # noqa: S202
+    if not locations.versions.is_file( ):
+        context = "published" if use_extant else "local"
+        print( f"No versions manifest found for {context} website. "
+               f"Run 'website update' first." )
+        return
+    with locations.versions.open( 'r' ) as file:
+        data = __.json.load( file )
+    versions = data.get( 'versions', { } )
+    latest = data.get( 'latest_version' )
+    if not versions:
+        context = "published" if use_extant else "local"
+        print( f"No versions found in {context} manifest." )
+        return
+    context = "Published" if use_extant else "Local"
+    print( f"{context} versions:" )
+    for version, species in versions.items( ):
+        marker = " (latest)" if version == latest else ""
+        species_list = ', '.join( species ) if species else "none"
+        print( f"  {version}{marker}: {species_list}" )
 def update(
     auxdata: __.Globals,
     version: str, *,
-    project_anchor: __.Absential[ __.Path ] = __.absent
+    project_anchor: __.Absential[ __.Path ] = __.absent,
+    use_extant: bool = False,
+    production: bool = False
 ) -> None:
     ''' Updates project website with latest documentation and coverage.
@@ -145,6 +207,9 @@ def update(
     from tarfile import open as tarfile_open
     locations = Locations.from_project_anchor( auxdata, project_anchor )
     locations.publications.mkdir( exist_ok = True, parents = True )
+    # --production implies --use-extant to prevent clobbering existing versions
+    if use_extant or production:
+        _fetch_publication_branch_and_tarball( locations )
     if locations.website.is_dir( ): __.shutil.rmtree( locations.website )
     locations.website.mkdir( exist_ok = True, parents = True )
     if locations.archive.is_file( ):
@@ -155,14 +220,86 @@ def update(
         loader = _jinja2.FileSystemLoader( locations.templates ),
         autoescape = True )
     index_data = _update_versions_json( locations, version, available_species )
+    _enhance_index_data_with_stable_dev( index_data )
+    _create_stable_dev_directories( locations, index_data )
     _update_index_html( locations, j2context, index_data )
     if ( locations.artifacts / 'coverage-pytest' ).is_dir( ):
         _update_coverage_badge( locations, j2context )
+        _update_version_coverage_badge( locations, j2context, version )
     ( locations.website / '.nojekyll' ).touch( )
     from .filesystem import chdir
     with chdir( locations.website ): # noqa: SIM117
         with tarfile_open( locations.archive, 'w:xz' ) as archive:
             archive.add( '.' )
+    if production: _update_publication_branch( locations, version )
+def _create_stable_dev_directories(
+    locations: Locations, data: dict[ __.typx.Any, __.typx.Any ]
+) -> None:
+    ''' Creates stable/ and development/ directories with current releases.
+        Copies the content from the identified stable and development versions
+        to stable/ and development/ directories to provide persistent URLs
+        that don't change when new versions are released.
+    '''
+    stable_version = data.get( 'stable_version' )
+    development_version = data.get( 'development_version' )
+    if stable_version:
+        stable_source = locations.website / stable_version
+        stable_dest = locations.website / 'stable'
+        if stable_dest.is_dir( ):
+            __.shutil.rmtree( stable_dest )
+        if stable_source.is_dir( ):
+            __.shutil.copytree( stable_source, stable_dest )
+    if development_version:
+        dev_source = locations.website / development_version
+        dev_dest = locations.website / 'development'
+        if dev_dest.is_dir( ):
+            __.shutil.rmtree( dev_dest )
+        if dev_source.is_dir( ):
+            __.shutil.copytree( dev_source, dev_dest )
+def _enhance_index_data_with_stable_dev(
+    data: dict[ __.typx.Any, __.typx.Any ]
+) -> None:
+    ''' Enhances index data with stable/development version information.
+        Identifies the latest stable release and latest development version
+        from the versions data and adds them as separate entries for the
+        stable/development table.
+    '''
+    from packaging.version import Version
+    versions = data.get( 'versions', { } )
+    if not versions:
+        data[ 'stable_dev_versions' ] = { }
+        return
+    stable_version = None
+    development_version = None
+    # Sort versions by packaging.version.Version for proper comparison
+    sorted_versions = sorted(
+        versions.items( ),
+        key = lambda entry: Version( entry[ 0 ] ),
+        reverse = True )
+    # Find latest stable (non-prerelease) and development (prerelease) versions
+    for version_string, species in sorted_versions:
+        version_obj = Version( version_string )
+        if not version_obj.is_prerelease and stable_version is None:
+            stable_version = ( version_string, species )
+        if version_obj.is_prerelease and development_version is None:
+            development_version = ( version_string, species )
+        if stable_version and development_version:
+            break
+    stable_dev_versions: dict[ str, tuple[ str, ... ] ] = { }
+    if stable_version:
+        stable_dev_versions[ 'stable (current)' ] = stable_version[ 1 ]
+        data[ 'stable_version' ] = stable_version[ 0 ]
+    if development_version:
+        stable_dev_versions[ 'development (current)' ] = (
+            development_version[ 1 ] )
+        data[ 'development_version' ] = development_version[ 0 ]
+    data[ 'stable_dev_versions' ] = stable_dev_versions
 def _extract_coverage( locations: Locations ) -> int:
@@ -184,6 +321,58 @@ def _extract_coverage( locations: Locations ) -> int:
     return __.math.floor( float( line_rate ) * 100 )
+def _fetch_publication_branch_and_tarball( locations: Locations ) -> None:
+    ''' Fetches publication branch and checks out existing tarball.
+        Attempts to fetch the publication branch from origin and checkout
+        the website tarball. Ignores failures if branch or tarball don't exist.
+    '''
+    with __.ctxl.suppress( Exception ):
+        __.subprocess.run(
+            [ 'git', 'fetch', 'origin', 'publication:publication' ],
+            cwd = locations.project,
+            check = False,
+            capture_output = True )
+    with __.ctxl.suppress( Exception ):
+        __.subprocess.run(
+            [ 'git', 'checkout', 'publication', '--',
+              str( locations.archive ) ],
+            cwd = locations.project,
+            check = False,
+            capture_output = True )
+def _generate_coverage_badge_svg(
+    locations: Locations, j2context: _jinja2.Environment
+) -> str:
+    ''' Generates coverage badge SVG content.
+        Returns the rendered SVG content for a coverage badge based on the
+        current coverage percentage. Colors indicate coverage quality:
+        - red: < 50%
+        - yellow: 50-79%
+        - green: >= 80%
+    '''
+    coverage = _extract_coverage( locations )
+    color = (
+        'red' if coverage < 50 else ( # noqa: PLR2004
+            'yellow' if coverage < 80 else 'green' ) ) # noqa: PLR2004
+    label_text = 'coverage'
+    value_text = f"{coverage}%"
+    label_width = len( label_text ) * 6 + 10
+    value_width = len( value_text ) * 6 + 15
+    total_width = label_width + value_width
+    template = j2context.get_template( 'coverage.svg.jinja' )
+    # TODO: Add error handling for template rendering failures.
+    return template.render(
+        color = color,
+        total_width = total_width,
+        label_text = label_text,
+        value_text = value_text,
+        label_width = label_width,
+        value_width = value_width )
 def _update_available_species(
     locations: Locations, version: str
 ) -> tuple[ str, ... ]:
@@ -204,30 +393,49 @@ def _update_coverage_badge(
     ''' Updates coverage badge SVG.
         Generates a color-coded coverage badge based on the current coverage
-        percentage. Colors indicate coverage quality:
-        - red: < 50%
-        - yellow: 50-79%
-        - green: >= 80%
+        percentage and writes it to the main coverage.svg location.
     '''
-    coverage = _extract_coverage( locations )
-    color = (
-        'red' if coverage < 50 else ( # noqa: PLR2004
-            'yellow' if coverage < 80 else 'green' ) ) # noqa: PLR2004
-    label_text = 'coverage'
-    value_text = f"{coverage}%"
-    label_width = len( label_text ) * 6 + 10
-    value_width = len( value_text ) * 6 + 15
-    total_width = label_width + value_width
-    template = j2context.get_template( 'coverage.svg.jinja' )
-    # TODO: Add error handling for template rendering failures.
+    svg_content = _generate_coverage_badge_svg( locations, j2context )
     with locations.coverage.open( 'w' ) as file:
-        file.write( template.render(
-            color = color,
-            total_width = total_width,
-            label_text = label_text,
-            value_text = value_text,
-            label_width = label_width,
-            value_width = value_width ) )
+        file.write( svg_content )
+def _update_publication_branch( locations: Locations, version: str ) -> None:
+    ''' Updates publication branch with new tarball.
+        Adds the tarball to git, commits to the publication branch, and pushes
+        to origin. Uses the same approach as the GitHub workflow.
+    '''
+    __.subprocess.run(
+        [ 'git', 'add', str( locations.archive ) ],
+        cwd = locations.project,
+        check = True )
+    # Commit to publication branch without checkout
+    # Get current tree hash
+    tree_result = __.subprocess.run(
+        [ 'git', 'write-tree' ],
+        cwd = locations.project,
+        check = True,
+        capture_output = True,
+        text = True )
+    tree_hash = tree_result.stdout.strip( )
+    # Create commit with publication branch as parent
+    commit_result = __.subprocess.run(
+        [ 'git', 'commit-tree', tree_hash, '-p', 'publication',
+          '-m', f"Update documents for publication. ({version})" ],
+        cwd = locations.project,
+        check = True,
+        capture_output = True,
+        text = True )
+    commit_hash = commit_result.stdout.strip( )
+    __.subprocess.run(
+        [ 'git', 'branch', '--force', 'publication', commit_hash ],
+        cwd = locations.project,
+        check = True )
+    __.subprocess.run(
+        [ 'git', 'push', 'origin', 'publication:publication' ],
+        cwd = locations.project,
+        check = True )
 def _update_index_html(
@@ -246,6 +454,21 @@ def _update_index_html(
         file.write( template.render( **data ) )
+def _update_version_coverage_badge(
+    locations: Locations, j2context: _jinja2.Environment, version: str
+) -> None:
+    ''' Updates version-specific coverage badge SVG.
+        Generates a coverage badge for the specific version and places it
+        in the version's subtree. This allows each version to have its own
+        coverage badge accessible at version/coverage.svg.
+    '''
+    svg_content = _generate_coverage_badge_svg( locations, j2context )
+    version_coverage_path = locations.website / version / 'coverage.svg'
+    with version_coverage_path.open( 'w' ) as file:
+        file.write( svg_content )
 def _update_versions_json(
     locations: Locations,
     version: str,

emcd_projects-1.23a0/data/templates/website.html.jinja DELETED Viewed

@@ -1,58 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Available Releases</title>
-    <style>
-        table {
-            width: 100%;
-            border-collapse: collapse;
-        }
-        th, td {
-            padding: 8px;
-            text-align: left;
-            border-bottom: 1px solid #ddd;
-        }
-        th {
-            background-color: #f2f2f2;
-        }
-        tr:hover {
-            background-color: #f5f5f5;
-        }
-    </style>
-</head>
-<body>
-    <h1>Available Releases</h1>
-    <table>
-        <thead>
-            <tr>
-                <th>Version</th>
-                <th>Documentation</th>
-                <th>Coverage</th>
-            </tr>
-        </thead>
-        <tbody>
-        {% for version, attributes in versions.items() %}
-            <tr>
-                <td>{{ version }}</td>
-                <td>
-                {% if 'sphinx-html' in attributes %}
-                    <a href="{{ version }}/sphinx-html/index.html">Docs</a>
-                {% else %}
-                    N/A
-                {% endif %}
-                </td>
-                <td>
-                {% if 'coverage-pytest' in attributes %}
-                    <a href="{{ version }}/coverage-pytest/index.html">Coverage</a>
-                {% else %}
-                    N/A
-                {% endif %}
-                </td>
-            </tr>
-        {% endfor %}
-        </tbody>
-    </table>
-</body>
-</html>