topmark 0.6.2__tar.gz → 0.7.0__tar.gz

{topmark-0.6.2/src/topmark.egg-info → topmark-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.6.2
+Version: 0.7.0
 Summary: A Python CLI to inspect, validate, and manage license and copyright headers.
 Author-email: Olivier Biot <olivier.biot@gmail.com>
 License-Expression: MIT
@@ -79,6 +79,56 @@ Full documentation is available on Read the Docs: <https://topmark.readthedocs.i
 This README is the canonical, complete introduction for GitHub/PyPI. The docs site provides a
 concise landing page and deep links into topics (install, usage, CI, API, etc.).
 
+## 📝 Example headers
+
+TopMark inserts headers that are tailored to the comment style and conventions of each file type. Here are examples of how TopMark headers appear in different file formats:
+
+```bash
+#!/bin/bash
+
+# topmark:header:start
+#
+#   project   : TopMark
+#   file      : script.sh
+#   license   : MIT
+#   copyright : (c) 2025 Olivier Biot
+
+# topmark:header:end
+
+echo "Hello, World!"
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+topmark:header:start
+
+  project   : TopMark
+  file      : config.xml
+  license   : MIT
+  copyright : (c) 2025 Olivier Biot
+
+topmark:header:end
+-->
+
+<configuration>
+    <!-- XML content here -->
+</configuration>
+```
+
+```javascript
+// topmark:header:start
+//
+//   project   : TopMark
+//   file      : app.js
+//   license   : MIT
+//   copyright : (c) 2025 Olivier Biot
+//
+// topmark:header:end
+
+console.log("Hello, World!");
+```
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -193,9 +243,12 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version in JSON format
+# Output TopMark version (PEP 440) in JSON format
 topmark version --format json
 
+# Output TopMark version (SemVer) to stdout
+topmark version --semver
+
 # Apply changes to files in-place
 topmark check --apply src/
 

{topmark-0.6.2 → topmark-0.7.0}/README.md

@@ -28,6 +28,56 @@ Full documentation is available on Read the Docs: <https://topmark.readthedocs.i
 This README is the canonical, complete introduction for GitHub/PyPI. The docs site provides a
 concise landing page and deep links into topics (install, usage, CI, API, etc.).
 
+## 📝 Example headers
+
+TopMark inserts headers that are tailored to the comment style and conventions of each file type. Here are examples of how TopMark headers appear in different file formats:
+
+```bash
+#!/bin/bash
+
+# topmark:header:start
+#
+#   project   : TopMark
+#   file      : script.sh
+#   license   : MIT
+#   copyright : (c) 2025 Olivier Biot
+
+# topmark:header:end
+
+echo "Hello, World!"
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+topmark:header:start
+
+  project   : TopMark
+  file      : config.xml
+  license   : MIT
+  copyright : (c) 2025 Olivier Biot
+
+topmark:header:end
+-->
+
+<configuration>
+    <!-- XML content here -->
+</configuration>
+```
+
+```javascript
+// topmark:header:start
+//
+//   project   : TopMark
+//   file      : app.js
+//   license   : MIT
+//   copyright : (c) 2025 Olivier Biot
+//
+// topmark:header:end
+
+console.log("Hello, World!");
+```
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -142,9 +192,12 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version in JSON format
+# Output TopMark version (PEP 440) in JSON format
 topmark version --format json
 
+# Output TopMark version (SemVer) to stdout
+topmark version --semver
+
 # Apply changes to files in-place
 topmark check --apply src/
 

{topmark-0.6.2 → topmark-0.7.0}/pyproject.toml

@@ -10,7 +10,7 @@
 
 [project]
 name = "topmark"
-version = "0.6.2"
+version = "0.7.0" # PEP 440: "X.Y.Z.devN", "X.Y.ZrcN", or "X.Y.Z"
 description = "A Python CLI to inspect, validate, and manage license and copyright headers."
 authors = [{ name = "Olivier Biot", email = "olivier.biot@gmail.com" }]
 license = "MIT"

{topmark-0.6.2 → topmark-0.7.0}/src/topmark/cli/commands/version.py

@@ -23,6 +23,7 @@ from topmark.cli.cli_types import EnumChoiceParam
 from topmark.cli.cmd_common import get_effective_verbosity
 from topmark.cli_shared.utils import OutputFormat
 from topmark.constants import TOPMARK_VERSION
+from topmark.utils.version import pep440_to_semver
 
 if TYPE_CHECKING:
     from topmark.cli_shared.console_api import ConsoleLike
@@ -32,6 +33,12 @@ if TYPE_CHECKING:
     name="version",
     help="Show the current version of TopMark.",
 )
+@click.option(
+    "--semver",
+    is_flag=True,
+    default=False,
+    help="Render the version as SemVer instead of PEP 440 (maps rc→-rc.N, dev→-dev.N).",
+)
 @click.option(
     "--format",
     "output_format",
@@ -42,6 +49,7 @@ if TYPE_CHECKING:
 def version_command(
     *,
     output_format: OutputFormat | None = None,
+    semver: bool = False,
 ) -> None:
     """Show the current version of TopMark.
 
@@ -49,6 +57,7 @@ def version_command(
 
     Args:
         output_format (OutputFormat | None): Optional output format (plain text or markdown).
+        semver (bool): Return version identifier in `semver` if True, PEP440 (default) if False.
     """
     ctx = click.get_current_context()
     ctx.ensure_object(dict)
@@ -57,21 +66,32 @@ def version_command(
     # Determine effective program-output verbosity for gating extra details
     vlevel = get_effective_verbosity(ctx)
 
-    topmark_version = TOPMARK_VERSION
+    topmark_version: str = TOPMARK_VERSION
     fmt: OutputFormat = output_format or OutputFormat.DEFAULT
-
+    version_text: str = topmark_version
+    if semver:
+        try:
+            version_text = pep440_to_semver(topmark_version)
+        except ValueError as exc:
+            # Fall back to raw version; if verbose, surface the reason.
+            if vlevel > 0:
+                console.print(console.styled(f"[warn] {exc}", bold=True))
+
+    format: str = "semver" if semver else "pep440"
     if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):
         import json
 
-        console.print(json.dumps({"topmark_version": topmark_version}))
+        console.print(json.dumps({"version": version_text, "format": format}))
     elif fmt == OutputFormat.MARKDOWN:
         console.print("# TopMark Version\n")
-        console.print(f"**TopMark version {topmark_version}**")
+        console.print(f"**TopMark version ({format}): {version_text}**")
     else:  # Plain text (default)
         if vlevel > 0:
-            console.print(console.styled("TopMark version:\n", bold=True, underline=True))
-            console.print(f"    {console.styled(topmark_version, bold=True)}")
+            console.print(
+                console.styled(f"TopMark version ({format}):\n", bold=True, underline=True)
+            )
+            console.print(f"    {console.styled(version_text, bold=True)}")
         else:
-            console.print(console.styled(topmark_version, bold=True))
+            console.print(console.styled(version_text, bold=True))
 
     # No explicit return needed for Click commands.

topmark-0.7.0/src/topmark/utils/version.py

@@ -0,0 +1,78 @@
+# topmark:header:start
+#
+#   project      : TopMark
+#   file         : version.py
+#   file_relpath : src/topmark/utils/version.py
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""Version utilities for TopMark."""
+
+import re
+
+# Recognize the subset of PEP 440 we actually emit:
+#   X.Y.Z
+#   X.Y.ZrcN
+#   X.Y.ZaN / X.Y.ZbN
+#   X.Y.Z.devN
+#   +local (optional)
+# We deliberately do NOT accept .postN here (no clean SemVer equivalent).
+_PEP440_RE: re.Pattern[str] = re.compile(
+    r"""
+    ^
+    (?P<major>0|[1-9]\d*)\.
+    (?P<minor>0|[1-9]\d*)\.
+    (?P<patch>0|[1-9]\d*)
+    (?:
+      (?P<pre_label>a|b|rc)(?P<pre_num>\d+)
+    )?
+    (?:
+      \.post(?P<post>\d+)
+    )?
+    (?:
+      \.dev(?P<dev>\d+)
+    )?
+    (?:
+      \+(?P<local>[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)
+    )?
+    $
+    """,
+    re.VERBOSE,
+)
+
+
+def pep440_to_semver(pep440_version: str) -> str:
+    """Convert (our) PEP 440 to SemVer.
+
+    Maps:
+      rcN  -> -rc.N
+      aN   -> -alpha.N
+      bN   -> -beta.N
+      devN -> -dev.N (after any pre-release)
+      +local kept as-is
+
+    Args:
+        pep440_version (str): The version in PEP 440 format
+
+    Returns:
+        str: The version in SemVer format.
+
+    Raises:
+        ValueError: on post releases.
+    """
+    m: re.Match[str] | None = _PEP440_RE.match(pep440_version)
+    if not m:
+        raise ValueError(f"Not a recognized PEP 440 version: {pep440_version!r}")
+    if m.group("post") is not None:
+        raise ValueError(f"Post-releases are not valid SemVer: {pep440_version!r}")
+    major, minor, patch = m.group("major"), m.group("minor"), m.group("patch")
+    base: str = f"{major}.{minor}.{patch}"
+    pre = ""
+    if m.group("pre_label"):
+        lbl: str = {"a": "alpha", "b": "beta", "rc": "rc"}[m.group("pre_label")]
+        pre: str = f"-{lbl}.{m.group('pre_num')}"
+    dev: str = f"{'.' if pre else '-'}dev.{m.group('dev')}" if m.group("dev") else ""
+    local: str = f"+{m.group('local')}" if m.group("local") else ""
+    return f"{base}{pre}{dev}{local}"

{topmark-0.6.2 → topmark-0.7.0/src/topmark.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.6.2
+Version: 0.7.0
 Summary: A Python CLI to inspect, validate, and manage license and copyright headers.
 Author-email: Olivier Biot <olivier.biot@gmail.com>
 License-Expression: MIT
@@ -79,6 +79,56 @@ Full documentation is available on Read the Docs: <https://topmark.readthedocs.i
 This README is the canonical, complete introduction for GitHub/PyPI. The docs site provides a
 concise landing page and deep links into topics (install, usage, CI, API, etc.).
 
+## 📝 Example headers
+
+TopMark inserts headers that are tailored to the comment style and conventions of each file type. Here are examples of how TopMark headers appear in different file formats:
+
+```bash
+#!/bin/bash
+
+# topmark:header:start
+#
+#   project   : TopMark
+#   file      : script.sh
+#   license   : MIT
+#   copyright : (c) 2025 Olivier Biot
+
+# topmark:header:end
+
+echo "Hello, World!"
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+topmark:header:start
+
+  project   : TopMark
+  file      : config.xml
+  license   : MIT
+  copyright : (c) 2025 Olivier Biot
+
+topmark:header:end
+-->
+
+<configuration>
+    <!-- XML content here -->
+</configuration>
+```
+
+```javascript
+// topmark:header:start
+//
+//   project   : TopMark
+//   file      : app.js
+//   license   : MIT
+//   copyright : (c) 2025 Olivier Biot
+//
+// topmark:header:end
+
+console.log("Hello, World!");
+```
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -193,9 +243,12 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version in JSON format
+# Output TopMark version (PEP 440) in JSON format
 topmark version --format json
 
+# Output TopMark version (SemVer) to stdout
+topmark version --semver
+
 # Apply changes to files in-place
 topmark check --apply src/
 

{topmark-0.6.2 → topmark-0.7.0}/src/topmark.egg-info/SOURCES.txt

@@ -76,4 +76,5 @@ src/topmark/rendering/api.py
 src/topmark/rendering/formats.py
 src/topmark/utils/__init__.py
 src/topmark/utils/diff.py
-src/topmark/utils/file.py
+src/topmark/utils/file.py
+src/topmark/utils/version.py