apdev 0.1.0__tar.gz

apdev-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: apdev
+Version: 0.1.0
+Summary: Shared development tools for Python projects - character validation, circular import detection, and more
+Author-email: aipartnerup <tercel.yi@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://aipartnerup.com
+Project-URL: Documentation, https://github.com/aipartnerup/apdev
+Project-URL: Repository, https://github.com/aipartnerup/apdev
+Project-URL: Issues, https://github.com/aipartnerup/apdev/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# apdev (Python)
+
+Shared development tools for Python projects.
+
+## Installation
+
+```bash
+pip install apdev
+```
+
+For development:
+
+```bash
+pip install apdev[dev]
+```
+
+## Tools
+
+### check-chars
+
+Validate that files contain only allowed characters (ASCII, common emoji, and technical symbols like arrows and box-drawing characters).
+
+```bash
+# Check specific files
+apdev check-chars src/mypackage/*.py
+
+# Use with pre-commit (see below)
+```
+
+### check-imports
+
+Detect circular imports in a Python package.
+
+```bash
+# Specify package explicitly
+apdev check-imports --package mypackage --src-dir src
+
+# Or configure in pyproject.toml (see below)
+apdev check-imports
+```
+
+### release
+
+Interactive release automation for publishing Python packages to PyPI and GitHub. Auto-detects project name from `pyproject.toml` and GitHub repo from git remote.
+
+```bash
+# Run with auto-detected version from pyproject.toml
+apdev release
+
+# Or specify version explicitly
+apdev release 0.2.0
+```
+
+The command provides an interactive menu with steps:
+1. Version verification (checks `pyproject.toml` and `__init__.py` match)
+2. Status check (tag, build files, PyPI)
+3. Clean build files
+4. Build package (`python -m build`)
+5. Check package (`twine check`)
+6. Create git tag and push
+7. Create GitHub release (via `gh` CLI or API)
+8. Upload to PyPI (`twine upload`)
+
+Override auto-detection with environment variables:
+
+```bash
+PROJECT_NAME=mypackage GITHUB_REPO=owner/repo apdev release
+```
+
+## Configuration
+
+Add to your project's `pyproject.toml`:
+
+```toml
+[tool.apdev]
+base_package = "mypackage"
+src_dir = "src"
+```
+
+## Pre-commit Integration
+
+```yaml
+repos:
+  - repo: https://github.com/aipartnerup/apdev
+    rev: python/v0.1.0
+    hooks:
+      - id: check-chars
+      - id: check-imports
+```
+
+Or use as a local hook with the pip-installed package:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: check-chars
+        name: apdev check-chars
+        entry: apdev check-chars
+        language: system
+        types_or: [text, python]
+
+      - id: check-imports
+        name: apdev check-imports
+        entry: apdev check-imports
+        language: system
+        pass_filenames: false
+        always_run: true
+```
+
+## License
+
+Apache-2.0

apdev-0.1.0/README.md

@@ -0,0 +1,113 @@
+# apdev (Python)
+
+Shared development tools for Python projects.
+
+## Installation
+
+```bash
+pip install apdev
+```
+
+For development:
+
+```bash
+pip install apdev[dev]
+```
+
+## Tools
+
+### check-chars
+
+Validate that files contain only allowed characters (ASCII, common emoji, and technical symbols like arrows and box-drawing characters).
+
+```bash
+# Check specific files
+apdev check-chars src/mypackage/*.py
+
+# Use with pre-commit (see below)
+```
+
+### check-imports
+
+Detect circular imports in a Python package.
+
+```bash
+# Specify package explicitly
+apdev check-imports --package mypackage --src-dir src
+
+# Or configure in pyproject.toml (see below)
+apdev check-imports
+```
+
+### release
+
+Interactive release automation for publishing Python packages to PyPI and GitHub. Auto-detects project name from `pyproject.toml` and GitHub repo from git remote.
+
+```bash
+# Run with auto-detected version from pyproject.toml
+apdev release
+
+# Or specify version explicitly
+apdev release 0.2.0
+```
+
+The command provides an interactive menu with steps:
+1. Version verification (checks `pyproject.toml` and `__init__.py` match)
+2. Status check (tag, build files, PyPI)
+3. Clean build files
+4. Build package (`python -m build`)
+5. Check package (`twine check`)
+6. Create git tag and push
+7. Create GitHub release (via `gh` CLI or API)
+8. Upload to PyPI (`twine upload`)
+
+Override auto-detection with environment variables:
+
+```bash
+PROJECT_NAME=mypackage GITHUB_REPO=owner/repo apdev release
+```
+
+## Configuration
+
+Add to your project's `pyproject.toml`:
+
+```toml
+[tool.apdev]
+base_package = "mypackage"
+src_dir = "src"
+```
+
+## Pre-commit Integration
+
+```yaml
+repos:
+  - repo: https://github.com/aipartnerup/apdev
+    rev: python/v0.1.0
+    hooks:
+      - id: check-chars
+      - id: check-imports
+```
+
+Or use as a local hook with the pip-installed package:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: check-chars
+        name: apdev check-chars
+        entry: apdev check-chars
+        language: system
+        types_or: [text, python]
+
+      - id: check-imports
+        name: apdev check-imports
+        entry: apdev check-imports
+        language: system
+        pass_filenames: false
+        always_run: true
+```
+
+## License
+
+Apache-2.0

apdev-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apdev"
+version = "0.1.0"
+description = "Shared development tools for Python projects - character validation, circular import detection, and more"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "aipartnerup", email = "tercel.yi@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "tomli>=1.1.0;python_version<'3.11'",
+]
+
+[project.scripts]
+apdev = "apdev.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+apdev = ["release.sh"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[project.urls]
+Homepage = "https://aipartnerup.com"
+Documentation = "https://github.com/aipartnerup/apdev"
+Repository = "https://github.com/aipartnerup/apdev"
+Issues = "https://github.com/aipartnerup/apdev/issues"

apdev-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apdev-0.1.0/src/apdev/__init__.py

@@ -0,0 +1,3 @@
+"""apdev - Shared development tools for Python projects."""
+
+__version__ = "0.1.0"

apdev-0.1.0/src/apdev/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running apdev as `python -m apdev`."""
+
+import sys
+
+from apdev.cli import main
+
+sys.exit(main())

apdev-0.1.0/src/apdev/check_chars.py

@@ -0,0 +1,79 @@
+"""Character validation tool.
+
+Checks that files contain only allowed characters: ASCII, common emoji,
+and standard technical symbols (arrows, box-drawing, math operators, etc.).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Allowed Unicode ranges beyond ASCII (0-127)
+EMOJI_RANGES: list[tuple[int, int]] = [
+    (0x1F300, 0x1F5FF),  # Symbols and Pictographs
+    (0x1F600, 0x1F64F),  # Emoticons
+    (0x1F680, 0x1F6FF),  # Transport and Map Symbols
+    (0x1F780, 0x1F7FF),  # Geometric Shapes Extended
+    (0x1F900, 0x1F9FF),  # Supplemental Symbols and Pictographs
+    (0x2600, 0x26FF),    # Miscellaneous Symbols
+    (0x2700, 0x27BF),    # Dingbats
+]
+
+EXTRA_ALLOWED_RANGES: list[tuple[int, int]] = [
+    (0x0080, 0x00FF),  # Latin-1 Supplement
+    (0x2000, 0x206F),  # General Punctuation
+    (0x2100, 0x214F),  # Letterlike Symbols
+    (0x2190, 0x21FF),  # Arrows
+    (0x2200, 0x22FF),  # Mathematical Operators
+    (0x2300, 0x23FF),  # Miscellaneous Technical
+    (0x2500, 0x257F),  # Box Drawing
+    (0x25A0, 0x25FF),  # Geometric Shapes
+    (0x2B00, 0x2BFF),  # Miscellaneous Symbols and Arrows
+    (0xFE00, 0xFE0F),  # Variation Selectors
+]
+
+_ALL_RANGES = EMOJI_RANGES + EXTRA_ALLOWED_RANGES
+
+
+def is_allowed_char(c: str) -> bool:
+    """Return True if the character is in the allowed set."""
+    code = ord(c)
+    if code <= 127:
+        return True
+    for start, end in _ALL_RANGES:
+        if start <= code <= end:
+            return True
+    return False
+
+
+def check_file(path: Path, *, max_problems: int = 5) -> list[str]:
+    """Check a single file for illegal characters.
+
+    Returns a list of problem descriptions (empty if the file is clean).
+    """
+    problems: list[str] = []
+    try:
+        content = path.read_text(encoding="utf-8")
+        for i, char in enumerate(content, 1):
+            if not is_allowed_char(char):
+                problems.append(
+                    f"Illegal character at position {i}: {char!r} (U+{ord(char):04X})"
+                )
+                if len(problems) >= max_problems:
+                    break
+    except Exception as e:
+        problems.append(f"Failed to read file: {e}")
+    return problems
+
+
+def check_paths(paths: list[Path]) -> int:
+    """Check multiple files. Returns 0 if all clean, 1 if any have problems."""
+    has_error = False
+    for path in paths:
+        problems = check_file(path)
+        if problems:
+            has_error = True
+            print(f"\n{path} contains illegal characters:")
+            for p in problems:
+                print(f"  {p}")
+    return 1 if has_error else 0

apdev-0.1.0/src/apdev/check_imports.py

@@ -0,0 +1,143 @@
+"""Circular import detection tool.
+
+Builds a module-level dependency graph within a Python package
+and reports any circular import chains.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+
+class ImportAnalyzer(ast.NodeVisitor):
+    """Collect fully-qualified imports from a single Python file."""
+
+    def __init__(self) -> None:
+        self.imports: set[str] = set()
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            self.imports.add(alias.name)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        if node.module:
+            self.imports.add(node.module)
+
+
+def file_to_module(file_path: Path, src_dir: Path) -> str:
+    """Convert a file path to a dotted module name."""
+    rel = file_path.relative_to(src_dir)
+    parts = list(rel.parts)
+    if parts[-1] == "__init__.py":
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1].removesuffix(".py")
+    return ".".join(parts)
+
+
+def _resolve_imports(raw_imports: set[str], base_package: str) -> set[str]:
+    """Filter imports to those within the base package."""
+    resolved: set[str] = set()
+    for imp in raw_imports:
+        if imp == base_package or imp.startswith(base_package + "."):
+            resolved.add(imp)
+    return resolved
+
+
+def build_dependency_graph(
+    src_dir: Path,
+    *,
+    base_package: str,
+) -> dict[str, set[str]]:
+    """Build a module-to-module dependency graph for the given package."""
+    graph: dict[str, set[str]] = defaultdict(set)
+
+    for py_file in src_dir.rglob("*.py"):
+        if "__pycache__" in py_file.parts:
+            continue
+
+        module_name = file_to_module(py_file, src_dir)
+        if not module_name:
+            continue
+
+        try:
+            source = py_file.read_text(encoding="utf-8")
+            tree = ast.parse(source, filename=str(py_file))
+        except Exception as e:
+            print(f"Warning: could not parse {py_file}: {e}", file=sys.stderr)
+            continue
+
+        analyzer = ImportAnalyzer()
+        analyzer.visit(tree)
+
+        deps = _resolve_imports(analyzer.imports, base_package)
+        deps.discard(module_name)
+        graph[module_name] = deps
+
+    return graph
+
+
+def find_cycles(graph: dict[str, set[str]]) -> list[list[str]]:
+    """Find all elementary cycles in the dependency graph using DFS."""
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[str, int] = defaultdict(int)
+    path: list[str] = []
+    cycles: list[list[str]] = []
+
+    def dfs(node: str) -> None:
+        color[node] = GRAY
+        path.append(node)
+        for neighbor in sorted(graph.get(node, set())):
+            if color[neighbor] == GRAY and neighbor in path:
+                idx = path.index(neighbor)
+                cycle = path[idx:] + [neighbor]
+                cycles.append(cycle)
+            elif color[neighbor] == WHITE:
+                dfs(neighbor)
+        path.pop()
+        color[node] = BLACK
+
+    for node in sorted(graph):
+        if color[node] == WHITE:
+            dfs(node)
+
+    # Deduplicate by normalizing cycle rotation
+    unique: list[list[str]] = []
+    seen: set[tuple[str, ...]] = set()
+    for cycle in cycles:
+        ring = cycle[:-1]
+        min_idx = ring.index(min(ring))
+        normalized = tuple(ring[min_idx:] + ring[:min_idx])
+        if normalized not in seen:
+            seen.add(normalized)
+            unique.append(cycle)
+
+    return unique
+
+
+def check_circular_imports(
+    src_dir: Path,
+    *,
+    base_package: str,
+) -> int:
+    """Run circular import detection. Returns 0 if clean, 1 if cycles found."""
+    if not src_dir.exists():
+        print(f"Error: {src_dir}/ directory not found", file=sys.stderr)
+        return 1
+
+    graph = build_dependency_graph(src_dir, base_package=base_package)
+    print(f"Scanned {len(graph)} modules")
+
+    cycles = find_cycles(graph)
+    if cycles:
+        print(f"\nFound {len(cycles)} circular import(s):\n")
+        for i, cycle in enumerate(cycles, 1):
+            print(f"  Cycle {i}: {' -> '.join(cycle)}")
+        print()
+        return 1
+
+    print("No circular imports detected.")
+    return 0

apdev-0.1.0/src/apdev/cli.py

@@ -0,0 +1,116 @@
+"""Command-line interface for apdev."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import apdev
+from apdev.check_chars import check_paths
+from apdev.check_imports import check_circular_imports
+from apdev.config import load_config
+
+
+def _get_release_script() -> Path:
+    """Locate the bundled release.sh script."""
+    ref = importlib.resources.files("apdev").joinpath("release.sh")
+    return Path(str(ref))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="apdev",
+        description="Shared development tools for Python projects",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"apdev {apdev.__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # check-chars
+    chars_parser = subparsers.add_parser(
+        "check-chars",
+        help="Validate files contain only allowed characters",
+    )
+    chars_parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="Files to check",
+    )
+
+    # check-imports
+    imports_parser = subparsers.add_parser(
+        "check-imports",
+        help="Detect circular imports in a Python package",
+    )
+    imports_parser.add_argument(
+        "--package",
+        dest="base_package",
+        help="Base package name (e.g. apflow). Reads from [tool.apdev] if omitted.",
+    )
+    imports_parser.add_argument(
+        "--src-dir",
+        dest="src_dir",
+        help="Source directory containing the package (default: src)",
+    )
+
+    # release
+    release_parser = subparsers.add_parser(
+        "release",
+        help="Interactive release automation (build, tag, GitHub release, PyPI upload)",
+    )
+    release_parser.add_argument(
+        "version",
+        nargs="?",
+        help="Version to release (auto-detected from pyproject.toml if omitted)",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the apdev CLI."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "check-chars":
+        return check_paths(args.files)
+
+    if args.command == "check-imports":
+        config = load_config()
+        base_package = args.base_package or config.get("base_package")
+        src_dir_str = args.src_dir or config.get("src_dir", "src")
+        src_dir = Path(src_dir_str)
+
+        if not base_package:
+            print(
+                "Error: --package is required (or set base_package in [tool.apdev])",
+                file=sys.stderr,
+            )
+            return 1
+
+        return check_circular_imports(src_dir, base_package=base_package)
+
+    if args.command == "release":
+        script = _get_release_script()
+        if not script.is_file():
+            print("Error: release.sh not found in package", file=sys.stderr)
+            return 1
+        cmd = ["bash", str(script)]
+        if args.version:
+            cmd.append(args.version)
+        result = subprocess.run(cmd, env={**os.environ})
+        return result.returncode
+
+    return 0