ipctools 0.0.0__tar.gz

ipctools-0.0.0/LICENSE

@@ -0,0 +1,15 @@
+Inter-process communication tools.
+Copyright (C) 2026  Narvin Singh
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

ipctools-0.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.3
+Name: ipctools
+Version: 0.0.0
+Summary: Inter-process communication tools.
+Author: Narvin Singh
+Author-email: Narvin Singh <Narvin.A.Singh@gmail.com>
+License: Inter-process communication tools.
+         Copyright (C) 2026  Narvin Singh
+         
+         This program is free software: you can redistribute it and/or modify
+         it under the terms of the GNU General Public License as published by
+         the Free Software Foundation, either version 3 of the License, or
+         (at your option) any later version.
+         
+         This program is distributed in the hope that it will be useful,
+         but WITHOUT ANY WARRANTY; without even the implied warranty of
+         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+         GNU General Public License for more details.
+         
+         You should have received a copy of the GNU General Public License
+         along with this program.  If not, see <https://www.gnu.org/licenses/>.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Requires-Dist: python-docs-theme~=2025.12 ; extra == 'doc'
+Requires-Dist: sphinx~=9.1 ; extra == 'doc'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://gitlab.com/narvin/ipctools
+Project-URL: Repository, https://gitlab.com/narvin/ipctools
+Project-URL: Bug Tracker, https://gitlab.com/narvin/ipctools/-/issues
+Provides-Extra: doc
+Description-Content-Type: text/x-rst
+
+Ipctools
+########
+
+Inter-process communication tools.
+
+This is a template project that can be used to publish a package to `PyPI
+<https://pypi.org/>`__.
+
+Installation
+************
+
+Create a ``.env`` file in the project directory with your `PyPI token
+<https://pypi.org/help/#apitoken>`__ so you can publish packages.
+
+.. code-block:: shell
+
+   echo "PYPI_TOKEN=<your token>" > .env
+
+``git`` and ``uv`` should be installed on your system. ``uv`` may be installed
+by running ``make uv``.
+
+Unless you use the ``unsafe`` option, then you must set ``GIT_PATH`` and
+``UV_PATH`` to the location of these tools on your system. You may also set
+these in the ``.env`` file.
+
+Usage
+*****
+
+Apply data to the template.
+
+.. code-block:: shell
+
+   uv run -m src.pypireg apply -n "<project name>" -d "<project description>"
+
+The project will be customized with the data, and files and directories will be
+renamed. You may copy, and rename the project directory, then begin working on
+the customized project. There are ``make`` recipes to install the project,
+build documentation, perform code quality checks, run unit tests, and build and
+publish the package to PyPI. The first thing you may want to do is attempt to
+publish your new package in order to reserve the name if it is available.
+
+Restore the project to its original state.
+
+.. note::
+
+   Since the package directory has been renamed, instead of ``src.pypireg``,
+   you must reference the package by its new name.
+
+.. code-block:: shell
+
+   uv run -m src.<project name> restore
+

ipctools-0.0.0/README.rst

@@ -0,0 +1,52 @@
+Ipctools
+########
+
+Inter-process communication tools.
+
+This is a template project that can be used to publish a package to `PyPI
+<https://pypi.org/>`__.
+
+Installation
+************
+
+Create a ``.env`` file in the project directory with your `PyPI token
+<https://pypi.org/help/#apitoken>`__ so you can publish packages.
+
+.. code-block:: shell
+
+   echo "PYPI_TOKEN=<your token>" > .env
+
+``git`` and ``uv`` should be installed on your system. ``uv`` may be installed
+by running ``make uv``.
+
+Unless you use the ``unsafe`` option, then you must set ``GIT_PATH`` and
+``UV_PATH`` to the location of these tools on your system. You may also set
+these in the ``.env`` file.
+
+Usage
+*****
+
+Apply data to the template.
+
+.. code-block:: shell
+
+   uv run -m src.pypireg apply -n "<project name>" -d "<project description>"
+
+The project will be customized with the data, and files and directories will be
+renamed. You may copy, and rename the project directory, then begin working on
+the customized project. There are ``make`` recipes to install the project,
+build documentation, perform code quality checks, run unit tests, and build and
+publish the package to PyPI. The first thing you may want to do is attempt to
+publish your new package in order to reserve the name if it is available.
+
+Restore the project to its original state.
+
+.. note::
+
+   Since the package directory has been renamed, instead of ``src.pypireg``,
+   you must reference the package by its new name.
+
+.. code-block:: shell
+
+   uv run -m src.<project name> restore
+

ipctools-0.0.0/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "ipctools"
+version = "0.0.0"
+authors = [
+    {name = "Narvin Singh", email = "Narvin.A.Singh@gmail.com"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent"
+]
+description = "Inter-process communication tools."
+readme = "README.rst"
+license = {file = "LICENSE"}
+requires-python = ">=3.12"
+
+dependencies = []
+
+[project.optional-dependencies]
+doc = [
+    "python-docs-theme~=2025.12",
+    "sphinx~=9.1",
+]
+
+[dependency-groups]
+dev = [
+    "mypy~=1.19",
+    "pre-commit~=4.5",
+    "pytest~=9.0",
+    "ruff~=0.15.1",
+    "sphinx-lint~=1.0",
+    "yamllint~=1.38",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/narvin/ipctools"
+Repository = "https://gitlab.com/narvin/ipctools"
+"Bug Tracker" = "https://gitlab.com/narvin/ipctools/-/issues"
+
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # flake8-commas
+    "COM812",  # Trailing comma missing
+
+    # pydocstyle
+    "D203",    # 1 blank line required before class docstring
+    "D205",    # 1 blank line required between summary line and description
+    "D212",    # Multi-line docstring summary should start at the first line
+    "D400",    # First line should end with a period
+    "D415",    # First line should end with a period, question mark, or exclamation point
+
+    # Error
+    "E501",    # Line too long ({width} > {limit})
+    "E731",    # Do not assign a lambda expression, use a def
+
+    # eradicate
+    "ERA001",  # Found commented-out code
+
+    # flake8-fixme
+    "FIX002",  # Line contains TODO, consider resolving the issue
+
+    # flake8-implicit-str-concat
+    "ISC001",  # Implicitly concatenated string literals on one line
+
+    # flake8-pytest-style
+    "PT009",   # Use a regular assert instead of unittest-style {assertion}
+    "PT027",   # Use pytest.raises instead of unittest-style {assertion}
+
+    # flake8-todos
+    "TD003",   # Missing issue link on the line following this TODO
+]
+fixable = [
+    "F401",     # unused import
+    "F541",     # f-string without any placeholders
+
+    # isort
+    "I001",    # Import block is un-sorted or un-formatted
+
+    # Ruff-specific rules
+    "RUF022",  # `__all__` is not sorted
+    "RUF100",  # Unused noqa directive
+]
+isort.split-on-trailing-comma = false
+pydocstyle.convention = "google"
+

ipctools-0.0.0/src/ipctools/__init__.py

@@ -0,0 +1,8 @@
+"""The main package."""
+
+from importlib import metadata
+
+__project__ = "Ipctools"
+__distribution__ = "ipctools"
+__version__ = metadata.version("ipctools")
+__authors__ = ["Narvin Singh"]

ipctools-0.0.0/src/ipctools/__main__.py

@@ -0,0 +1,59 @@
+"""The package entry point."""
+
+import argparse
+import logging
+
+from . import ipctools
+
+
+def apply_name(name: str, desc: str, author: list[str] | None, *, unsafe: bool) -> None:
+    """Stub for apply"""
+    logging.getLogger(__name__).debug("applying name: %s and description: %s", name, desc)
+    ipctools.apply(name, desc, authors=author, unsafe=unsafe)
+
+
+def revert_apply_name(*, unsafe: bool) -> None:
+    """Stub for revert_apply_name"""
+    logging.getLogger(__name__).debug("restoring project")
+    ipctools.restore(unsafe=unsafe)
+
+
+def main() -> int:
+    """The entry point function."""
+    parser = argparse.ArgumentParser(prog="{{PROJECT}}", description="{{DESCRIPTION}}")
+    parser_common = argparse.ArgumentParser(add_help=False)
+    parser_common.add_argument(
+        "-l",
+        "--log-level",
+        choices=logging.getLevelNamesMapping().keys(),
+        default="DEBUG",
+        help="The logging level",
+    )
+    parser_common.add_argument(
+        "-u",
+        "--unsafe",
+        action="store_true",
+        help="If not set, then environment variables with tool paths must be defined",
+    )
+    subparsers = parser.add_subparsers(title="commands")
+    parser_apply = subparsers.add_parser(
+        "apply", parents=[parser_common], help="Apply data to the project"
+    )
+    parser_apply.add_argument("-n", "--name", required=True, help="The project name")
+    parser_apply.add_argument("-d", "--desc", required=True, help="The project description")
+    parser_apply.add_argument("-a", "--author", action="append", help="A project author")
+    parser_apply.set_defaults(func=apply_name)
+    parser_restore = subparsers.add_parser(
+        "restore", parents=[parser_common], help="Restore the pypireg project to its original state"
+    )
+    parser_restore.set_defaults(func=revert_apply_name)
+    args = parser.parse_args()
+    logging.basicConfig(level=args.log_level)
+    logger = logging.getLogger(__name__)
+    logger.debug("args: %s", args)
+    args.func(**{k: v for k, v in args.__dict__.items() if k not in {"func", "log_level"}})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ipctools-0.0.0/src/ipctools/ipctools.py

@@ -0,0 +1,150 @@
+"""The main module."""
+
+import configparser
+import functools
+import json
+import os
+import pathlib
+import shutil
+import subprocess
+import tomllib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+@functools.lru_cache(1)
+def _projroot() -> pathlib.Path:
+    return pathlib.Path(__file__).parent.parent.parent
+
+
+@functools.lru_cache(1)
+def _load_env() -> configparser.ConfigParser:
+    parser = configparser.ConfigParser(allow_unnamed_section=True)
+    parser.read(_projroot() / ".env")
+    return parser
+
+
+def _tool_path(tool: str, default: str | None) -> str:
+    _load_env()
+    key = f"{tool.upper()}_PATH"
+    msg = f"set the environment variable `{key}`, or add it to your `.env` file"
+    path = os.getenv(key)
+    if not path:
+        parser = _load_env()
+        try:
+            path = parser.get(configparser.UNNAMED_SECTION, key)
+        except configparser.NoOptionError as exc:
+            raise RuntimeError(msg) from exc
+    if path:
+        return path
+    if default is None:
+        raise RuntimeError(msg)
+    return default
+
+
+@functools.lru_cache(2)
+def _git_path(*, unsafe: bool) -> str:
+    return _tool_path("git", "git" if unsafe else None)
+
+
+@functools.lru_cache(2)
+def _uv_path(*, unsafe: bool) -> str:
+    return _tool_path("uv", "uv" if unsafe else None)
+
+
+def _update_file_raw(path: pathlib.Path, spec: Mapping[str, str]) -> None:
+    with path.open("r+") as f:
+        template = f.read()
+        f.seek(0)
+        content = functools.reduce(
+            lambda acc, curr: acc.replace(curr[0], curr[1]), spec.items(), template
+        )
+        f.write(content)
+        f.truncate()
+
+
+def _update_file(path: pathlib.Path, spec: Mapping[str, str]) -> None:
+    _update_file_raw(path, {f"{{{{{k.upper()}}}}}": v for k, v in spec.items()})
+
+
+def _rename_file(path: pathlib.Path, name: str) -> None:
+    path.rename(path.parent / name)
+
+
+def _get_authors_str(authors: list[str] | None, *, unsafe: bool) -> str | None:
+    match authors:
+        case [] | None:
+            git = _git_path(unsafe=unsafe)
+            res = subprocess.run(  # noqa: S603
+                [git, "config", "get", "user.name"], capture_output=True, check=False
+            )
+            author = res.stdout.decode().strip()
+            return json.dumps([author]) or None
+        case _:
+            return json.dumps(authors)
+
+
+def apply(
+    name: str, description: str, *, authors: list[str] | None = None, unsafe: bool = False
+) -> None:
+    """Apply data to the project."""
+    uv = _uv_path(unsafe=unsafe)
+    authors_str = _get_authors_str(authors, unsafe=unsafe)
+    projroot = _projroot()
+    proper_name = name.title()
+    _update_file(projroot / "LICENSE", {"description": description})
+    _update_file(projroot / "pyproject.toml", {"project": name, "description": description})
+    _update_file_raw(projroot / "pyproject.toml", {'name = "pypireg"': f'name = "{name}"'})
+    _update_file(
+        projroot / "README.rst",
+        {
+            "project": proper_name,
+            "project_underline": "#" * len(proper_name),
+            "description": description,
+        },
+    )
+    _update_file(projroot / "doc" / "conf.py", {"project": name})
+    _update_file(projroot / "doc" / "index.rst", {"project": name})
+    _update_file(
+        projroot / "src" / "pypireg" / "__init__.py",
+        {
+            "project": proper_name,
+            "distribution": name,
+            "authors": json.dumps(authors) if authors is not None else "None",
+        },
+    )
+    _update_file_raw(
+        projroot / "src" / "pypireg" / "__init__.py",
+        {
+            '__version__ = metadata.version("pypireg")': f'__version__ = metadata.version("{name}")',
+            "__authors__ = None": f"__authors__ = {authors_str}",
+        },
+    )
+    _update_file_raw(
+        projroot / "src" / "pypireg" / "__main__.py",
+        {"from . import pypireg": f"from . import {name}", "pypireg.": f"{name}."},
+    )
+    _rename_file(projroot / "src" / "pypireg" / "pypireg.py", f"{name}.py")
+    _rename_file(projroot / "src" / "pypireg", name)
+    _rename_file(projroot / "test" / "pypireg", name)
+    shutil.rmtree(projroot / ".venv")
+    subprocess.run([uv, "sync"], cwd=projroot, check=False)  # noqa: S603
+    subprocess.run([uv, "run", "ruff", "format"], cwd=projroot, check=False)  # noqa: S603
+
+
+def restore(*, unsafe: bool = False) -> None:
+    """Restore the project to its original state."""
+    git = _git_path(unsafe=unsafe)
+    uv = _uv_path(unsafe=unsafe)
+    projroot = _projroot()
+    with pathlib.Path(projroot / "pyproject.toml").open("rb") as f:
+        pyproj = tomllib.load(f)
+        name = pyproj["project"]["name"]
+    _rename_file(projroot / "src" / name / f"{name}.py", "pypireg.py")
+    _rename_file(projroot / "src" / name, "pypireg")
+    _rename_file(projroot / "test" / name, "pypireg")
+    subprocess.run([git, "restore", "."], cwd=projroot, check=False)  # noqa: S603
+    shutil.rmtree(projroot / ".venv")
+    subprocess.run([uv, "sync"], cwd=projroot, check=False)  # noqa: S603