[NEW] Semantic Version Check v1.0

Semantic Version Check v1.0.0 Release

CHANGELOG.rst

@@ -2,6 +2,23 @@
 Changelog
 =========
 
+1.0.0 (2022-05-18)
+==================
+
+This is first fully featured and stable version of the `semantic_version_check` Python Package.
+
+It features the `check-semantic-version` cli, suitable for quick invocation through a console or running on a CI service.
+It also features the installable `semantic_version_check` python module (aka package or library)
+that provides the `check` as python code.
+
+Changes
+^^^^^^^
+
+feature
+"""""""
+- check a string's to verify if it matches the Semantic Version format
+
+
 0.0.1 (2022-05-18)
 ==================
 

README.rst

@@ -19,8 +19,8 @@ Features
 
 1. **semantic_version_check** `python package`
 
-   a. TODO Document a **Great Feature**
-   b. TODO Document another **Nice Feature**
+   a. CLI that can be usefull for quick checks, a script or in a CI pipeline
+   b. Semantic Version format check, using Regular Expressions
 2. Tested against multiple `platforms` and `python` versions
 
 
@@ -62,7 +62,20 @@ Using `pip` is the approved way for installing `semantic_version_check`.
     python3 -m pip install semantic_version_check
 
 
-TODO Document a use case
+| One Use Case for the semantic_version_check is to invoke its cli, through a console
+| and do SemVer check on a single input string.
+
+Open a console and run:
+
+.. code-block:: shell
+
+  semantic-version-check 1.0.0
+  echo $?
+  echo "Exit code is 0 meaning operation succeeded"
+
+  semantic-version-check 1.3
+  echo $?
+  echo "Exit code is 1, meaning operation failed"
 
 
 License
@@ -141,9 +154,9 @@ License
 
 .. Github Releases & Tags
 
-.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/semantic-version-check/v0.0.1/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/semantic-version-check/v1.0.0/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/semantic-version-check/compare/v0.0.1..master
+    :target: https://github.com/boromir674/semantic-version-check/compare/v1.0.0..master
 
 .. |commits_since_latest_github_release| image:: https://img.shields.io/github/commits-since/boromir674/semantic-version-check/latest?color=blue&logo=semver&sort=semver
     :alt: GitHub commits since latest release (by SemVer)

docs/contents/10_introduction.rst

@@ -2,11 +2,9 @@
 Introduction
 ============
 
-| This is **semantic-version-checker**, a *Python Package* desinged to ...
+| This is **semantic-version-check**, a *Python Package* desinged to check whether
+| a given string is formatted according to Semantic Version.
 
-| Goal of this project is to TODO Document
-| Additionally, TODO Document
 
 | This documentation aims to help people understand what are the package's features and to demonstrate
 | how to leverage them for their use cases.
-| It also presents the overall package design.

docs/contents/20_why_this_package.rst

@@ -4,12 +4,20 @@ Why this Package?
 
 So, why would one opt for this Package?
 
-It is **easy** to *install* (using pip) and intuitive to *use*.
+It is useful in automation scenarios, since it can be run through
+its cli (eg using a `bash` shell) and "exits" with 0 or 1 accordingly.
 
-**semantic-version-checker** features TODO Document
+It is useful whenever you are writing python and want to have a single source of truth
+for parsing and checking a string according to Semantic Version.
 
-Well-tested against multiple Python Interpreter versions (3.6 - 3.10),
+Specifically, the package exposes a regular expression
+(`from semantic_version_check import regex`) that can serve as a single source of truth
+to your python projects, whenever you need to do some SemVer parsing of string.
+
+Also, it is easy to *install* using `pip`.
+
+Finally, the package is well-tested against multiple
+Python Interpreter versions (from 3.6 to 3.10),
 tested on both *Linux* (Ubuntu) and *Darwin* (Macos) platforms.
 
-Tests trigger automatically on **CI**.
-The package's releases follow **Semantic Versioning**.
+This package's releases follow **Semantic Versioning** too :)

docs/contents/30_usage.rst

@@ -22,6 +22,19 @@ Assuming you have 'activated' a `python virtual environment`:
 Simple Use Case
 ---------------
 
-| Common Use Case for the semantic_version_check is to TODO Document
+| One Use Case for the semantic_version_check is to invoke its cli, through a console
+| and do SemVer check on a single input string.
 
-TODO Document
+Open a console and run:
+
+.. code-block:: shell
+
+  semantic-version-check 1.0.0
+  echo $?
+  echo "Exit code is 0 meaning operation succeeded"
+
+  semantic-version-check 1.3
+  echo $?
+  echo "Exit code is 1, meaning operation failed"
+
+Note: this use case may be useful for a CI pipeline.

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 ## Setuptools specific information
 name = semantic_version_check
-version = 0.0.1
+version = 1.0.0
 # renders on pypi as subtitle
 description = Check if a 'version' is a valid Semantic Version.
 long_description = file: README.rst
@@ -15,7 +15,7 @@ author_email = k.lampridis@hotmail.com
 # represents the web home page of the project
 url = https://github.com/boromir674/semantic-version-check
 
-download_url = https://github.com/boromir674/semantic-version-check/archive/v0.0.1.tar.gz
+download_url = https://github.com/boromir674/semantic-version-check/archive/v1.0.0.tar.gz
 
 
 ## PyPi specific information
@@ -25,7 +25,7 @@ project_urls =
     Documentation = https://semantic-version-check.readthedocs.io/
     Source Code = https://github.com/boromir674/semantic-version-check
     Changelog = https://github.com/boromir674/semantic-version-check/blob/master/CHANGELOG.rst
-    ; Code of Conduct = TODO
+    Code of Conduct = https://github.com/boromir674/semantic-version-check/blob/master/CONTRIBUTING.rst
     ; Mailing lists =
 
 
@@ -65,18 +65,26 @@ where=src
 
 [options.extras_require]
 docs =
-    furo>=2021.08.31
-    sphinx~=4.0
-    sphinx-argparse-cli>=1.5
-    sphinx-autodoc-typehints>=1.10
-    sphinx-rtd-theme==0.5.0
+    # furo >= 2021.08.31  # sphinx theme
+    sphinx ~= 4.0
+    sphinx-argparse-cli >= 1.5
+    sphinx-autodoc-typehints >= 1.10
+    sphinx-rtd-theme == 0.5.0
     sphinxcontrib-spelling
 test =
-    pytest>=6.2.4
-    pytest-cov>=2.12
-    pytest-xdist>=1.34
+    pytest >= 6.2.4
+    pytest-cov >= 2.12
+    pytest-click ~= 1.1.0
+    pytest-xdist >= 1.34
 typing =
     mypy
+    pytest >= 6.2.4
+    pytest-click ~= 1.1.0
+
+
+[options.entry_points]
+console_scripts =
+    check-semantic-version = semantic_version_check.__main__:main
 
 
 [options.package_data]

src/semantic_version_check/__init__.py

@@ -1 +1,5 @@
-__version__ = '0.0.1'
+__version__ = '1.0.0'
+
+from .main import regex, version_check
+
+__all__ = ['regex', 'version_check']

src/semantic_version_check/__main__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""Allow executing through `python -m semantic_version_check`.
+
+Allow Semantic Version Check to be executable through
+`python -m semantic_version_check`.
+"""
+from __future__ import absolute_import
+
+from semantic_version_check.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main(prog_name='semantic-version-check')

src/semantic_version_check/cli.py

@@ -0,0 +1,19 @@
+import sys
+
+import click
+
+from semantic_version_check.main import SemanticVersionFormatError, version_check
+
+
+@click.command()
+@click.argument('version')
+def main(version):
+
+    try:
+        version_check(version)
+    except SemanticVersionFormatError:
+        sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/semantic_version_check/main.py

@@ -0,0 +1,45 @@
+import re
+from typing import Callable, Match, Pattern
+
+regex = re.compile(
+    r'^(?P<major>0|[1-9]\d*)'
+    r'\.'
+    r'(?P<minor>0|[1-9]\d*)'
+    r'\.'
+    r'(?P<patch>0|[1-9]\d*)'
+    r'(?:-'
+    r'(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)'
+    r'(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?'
+    r'(?:\+'
+    r'(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
+)
+
+
+class RegExMatcher:
+    @staticmethod
+    def match(regex: Pattern, string: str) -> Match:
+        match_result = regex.match(string)
+        if not match_result:
+            raise SemanticVersionFormatError(
+                "Regex '{regex}' did not match string '{string}'".format(
+                    regex=regex.pattern, string=string
+                )
+            )
+        return match_result
+
+
+# Simple Adapter
+class VersionCheck:
+    def __init__(self, regex_matcher: Callable[[Pattern, str], Match]):
+        self._regex_matcher = regex_matcher
+
+    def __call__(self, string):
+        return self._regex_matcher(regex, string)
+
+
+class SemanticVersionFormatError(Exception):
+    pass
+
+
+# Simple callable
+version_check = VersionCheck(RegExMatcher.match)

tests/test_api.py

@@ -0,0 +1,76 @@
+import pytest
+
+
+@pytest.fixture
+def version_check():
+    from semantic_version_check import version_check
+
+    return version_check
+
+
+@pytest.fixture
+def reg_missmath():
+    from semantic_version_check.main import SemanticVersionFormatError
+
+    return SemanticVersionFormatError
+
+
+@pytest.fixture
+def regex():
+    from semantic_version_check import regex
+
+    return regex
+
+
+@pytest.mark.parametrize(
+    'version',
+    (
+        '1.2.0',
+        '1.0.0',
+        '200.5.0',
+        '0.5.0',
+        '0.0.1',
+        '1.0.0-alpha',
+        '0.0.1-alpha.1',
+        '3.1.5-alpha.beta',
+        '1.34.6-beta.11',
+        '1.0.0-alpha-beta',
+        '1.0.0-alpha-beta-a-b',
+        '1.0.0-alpha-beta.1.2.3-1-a-s',
+        '1.34.6-beta.11-1',
+        '2.0.12-rc.1',
+    ),
+)
+def test_version_check(version, version_check):
+    match_object = version_check(version)
+    assert match_object is not None
+    assert match_object.group(1)
+    assert match_object.group(2)
+    assert match_object.group(3)
+
+
+@pytest.mark.parametrize(
+    'version',
+    (
+        '1.0',
+        '200',
+        '1',
+        '0.5',
+        '1.0-alpha',
+        '1.0.0.alpha',
+        '0.1-alpha.1',
+        '3-alpha.beta',
+        '34.6-beta.11',
+        '2.0.12.1-rc.1',
+    ),
+)
+def test_wrong_version(version, version_check, regex, reg_missmath):
+    import re
+
+    with pytest.raises(
+        reg_missmath,
+        match="Regex '{regex}' did not match string '{string}'".format(
+            regex=re.escape(regex.pattern), string=version
+        ),
+    ):
+        version_check(version)