python-naming-linter 0.1.0__tar.gz

python_naming_linter-0.1.0/.claude/skills/commit/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: commit
+description: Create a git commit following the project's commit convention
+---
+
+Create a git commit following the project's commit convention defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+
+## Steps
+
+1. Read `CONTRIBUTING.md` to check the commit convention.
+2. Run `git status` and `git diff` to review all changes.
+3. Draft a commit message following the convention.
+4. Stage only relevant files (do NOT use `git add -A`). Exclude secrets and unrelated files.
+5. Commit using a HEREDOC for proper formatting:
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   <commit message here>
+
+   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+   EOF
+   )"
+   ```
+6. Run `git status` to verify success.
+7. If pre-commit hook fails, fix the issue and create a **new** commit (never amend).

python_naming_linter-0.1.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: release
+description: Create a new release by calculating the next version from conventional commits and pushing a git tag
+---
+
+Create a new release following the project's release process defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+
+The release workflow is defined in [.github/workflows/publish.yaml](../../../.github/workflows/publish.yaml).
+
+## Steps
+
+1. Read `CONTRIBUTING.md` to check the release process.
+2. Follow the steps described in the Release section.
+3. Ask the user to confirm the version before creating and pushing the tag.

python_naming_linter-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "python_naming_linter/**"
+      - "tests/**"
+      - "pyproject.toml"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: uv pip install --system -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: ty check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv pip install --system -e ".[dev]"
+      - run: pytest -v

python_naming_linter-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,59 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Generate full changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: pyproject.toml
+          args: --verbose
+        env:
+          OUTPUT: CHANGELOG.md
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Commit CHANGELOG.md
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          git commit -m "docs: Update CHANGELOG for ${{ github.ref_name }}" || true
+          git push origin HEAD:main
+      - name: Generate release notes
+        id: release_notes
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: pyproject.toml
+          args: --verbose --latest --strip header
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.release_notes.outputs.content }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: changelog
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

python_naming_linter-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/

python_naming_linter-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff check
+        name: ruff check (lint)
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff format
+        name: ruff format (format)
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: ty check
+        name: ty check (type check)
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        types: [python]

python_naming_linter-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,6 @@
+- id: python-naming-linter
+  name: Python Naming Linter
+  entry: pnl check
+  language: python
+  types: [python]
+  pass_filenames: false

python_naming_linter-0.1.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## Project Overview
+
+Python naming linter (`pnl`) - A CLI tool that lints naming conventions in Python projects.
+
+## Contributing
+
+Follow the conventions in [CONTRIBUTING.md](./CONTRIBUTING.md).

python_naming_linter-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+## Commit Convention
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) with [gitmoji](https://gitmoji.dev/) prefix.
+
+### Format
+
+```
+<gitmoji> <type>: <description>
+```
+
+- The first letter after the colon must be **capitalized**.
+- The description must be in **English**.
+
+### Types
+
+| Gitmoji | Type       | Description              |
+|---------|------------|--------------------------|
+| ✨      | `feat`     | New feature              |
+| 🐛      | `fix`      | Bug fix                  |
+| ♻️      | `refactor` | Code refactoring         |
+| 📝      | `docs`     | Documentation            |
+| ✅      | `test`     | Adding or updating tests |
+| 🔧      | `chore`    | Maintenance tasks        |
+| 👷      | `ci`       | CI/CD changes            |
+| ⚡      | `perf`     | Performance improvement  |
+
+### Examples
+
+```
+✨ feat: Add support for relative imports
+🐛 fix: Use exit code 2 for config file not found
+♻️ refactor: Simplify module resolver logic
+```
+
+## Pull Request Convention
+
+- PRs are always **squash merged**, so the PR title becomes the final commit message.
+- PR titles must follow the same format as commit messages (`<gitmoji> <type>: <description>`).
+- PR descriptions must be written in **English**.
+
+## Pre-commit Hooks
+
+This project uses [pre-commit](https://pre-commit.com/) for linting, formatting, and type checking.
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run manually
+pre-commit run --all-files
+```
+
+All commits must pass the pre-commit hooks before being accepted.
+
+## Release
+
+Releases are automated via GitHub Actions. You only need to create and push a version tag.
+
+### Steps
+
+1. Calculate the next version based on conventional commits:
+   ```bash
+   uvx git-cliff --bumped-version
+   ```
+2. Review the commits since the last tag:
+   ```bash
+   git log $(git describe --tags --abbrev=0)..HEAD --oneline
+   ```
+3. Push the latest commits to `main`:
+   ```bash
+   git push origin main
+   ```
+4. Create and push the tag:
+   ```bash
+   git tag <version>
+   git push origin <version>
+   ```
+
+The GitHub Actions workflow will then automatically:
+- Generate `CHANGELOG.md` and commit it to `main`
+- Create a GitHub Release with release notes
+- Publish the package to PyPI

python_naming_linter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heumsi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_naming_linter-0.1.0/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: python-naming-linter
+Version: 0.1.0
+Summary: A naming convention linter for Python projects
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty>=0.0.26; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-naming-linter
+
+A naming convention linter for Python projects. Define custom naming rules and enforce them with a single CLI command.
+
+## What It Does
+
+- Define naming rules for variables, functions, classes, modules, and packages
+- Apply rules to specific modules using pattern matching
+- Integrate into CI or pre-commit to keep your naming conventions consistent
+
+For Python developers who want to enforce team-specific naming conventions beyond what PEP 8 and ruff cover.
+
+## Installation
+
+```bash
+pip install python-naming-linter
+```
+
+Or with uv:
+
+```bash
+uv add python-naming-linter
+```
+
+## Quick Start
+
+Create `.python-naming-linter.yaml` in your project root:
+
+```yaml
+rules:
+  - name: bool-method-prefix
+    type: function
+    filter: { return_type: bool }
+    naming: { prefix: [is_, has_, should_] }
+
+  - name: exception-naming
+    type: class
+    filter: { base_class: Exception }
+    naming: { regex: "^[A-Z][a-zA-Z]+(NotFound|Invalid|Denied|Conflict|Failed)Error$" }
+
+apply:
+  - name: all
+    rules: [bool-method-prefix, exception-naming]
+    modules: "**"
+```
+
+Run:
+
+```bash
+pnl check
+```
+
+Output:
+
+```
+src/domain/service.py:12
+    [bool-method-prefix] validate (expected prefix: is_ | has_ | should_)
+
+src/domain/exceptions.py:8
+    [exception-naming] FilterError (expected pattern: ^[A-Z][a-zA-Z]+(NotFound|Invalid|...)Error$)
+
+Found 2 violation(s).
+```
+
+## Examples
+
+### Variable Naming — Match Type Annotation
+
+Enforce that variable names match their type annotation in snake_case:
+
+```yaml
+rules:
+  - name: attribute-matches-type
+    type: variable
+    filter: { target: attribute }
+    naming: { source: type_annotation, transform: snake_case }
+
+apply:
+  - name: domain-layer
+    rules: [attribute-matches-type]
+    modules: contexts.*.domain
+```
+
+This catches `repo: SubscriptionRepository` (should be `subscription_repository`).
+
+The `{prefix}_{expected}` form is also allowed — `source_object_context: ObjectContext` passes because it ends with `_object_context`.
+
+### Module Naming — Match Class Name
+
+Enforce that module filenames match the primary class they contain:
+
+```yaml
+rules:
+  - name: domain-module-naming
+    type: module
+    naming: { source: class_name, transform: snake_case }
+
+apply:
+  - name: domain-layer
+    rules: [domain-module-naming]
+    modules: contexts.*.domain
+```
+
+A file `custom.py` containing `class CustomObject` is a violation — it should be `custom_object.py`.
+
+### Combining Rules Per Layer
+
+Apply different rules to different parts of your codebase:
+
+```yaml
+rules:
+  - name: attribute-matches-type
+    type: variable
+    filter: { target: attribute }
+    naming: { source: type_annotation, transform: snake_case }
+
+  - name: bool-method-prefix
+    type: function
+    filter: { return_type: bool }
+    naming: { prefix: [is_, has_, should_] }
+
+  - name: exception-naming
+    type: class
+    filter: { base_class: Exception }
+    naming: { regex: "^[A-Z][a-zA-Z]+(NotFound|Invalid|Denied|Conflict|Failed)Error$" }
+
+  - name: domain-module-naming
+    type: module
+    naming: { source: class_name, transform: snake_case }
+
+  - name: constant-upper-case
+    type: variable
+    filter: { target: constant }
+    naming: { case: UPPER_CASE }
+
+apply:
+  - name: domain-layer
+    rules:
+      - attribute-matches-type
+      - bool-method-prefix
+      - domain-module-naming
+      - constant-upper-case
+    modules: contexts.*.domain
+
+  - name: global-exceptions
+    rules: [exception-naming]
+    modules: "**"
+```
+
+## Configuration
+
+### Rule Types
+
+| Type | Target |
+|------|--------|
+| `variable` | Variable names (attribute, parameter, local_variable, constant) |
+| `function` | Function/method names |
+| `class` | Class names (including exceptions) |
+| `module` | Module (file) names |
+| `package` | Package (directory) names |
+
+### Filter
+
+Each rule can narrow its scope with type-specific filters:
+
+| Type | Filter | Example Values |
+|------|--------|----------------|
+| `variable` | `target` | `attribute`, `parameter`, `local_variable`, `constant` |
+| `function` | `target` | `method`, `function` |
+| `function` | `return_type` | `bool` |
+| `function` | `decorator` | `staticmethod` |
+| `class` | `base_class` | `Exception` |
+| `class` | `decorator` | `dataclass` |
+
+### Naming Constraints
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `prefix` | Name must start with one of the listed prefixes | `[is_, has_]` |
+| `suffix` | Name must end with one of the listed suffixes | `[Repository, Service]` |
+| `regex` | Name must match a regular expression | `"^[A-Z][a-zA-Z]+Error$"` |
+| `source` + `transform` | Name must be derived from another element | `source: type_annotation`, `transform: snake_case` |
+| `case` | Name must follow a casing convention | `snake_case`, `PascalCase`, `UPPER_CASE` |
+
+### Include / Exclude
+
+Control which files are scanned:
+
+```yaml
+include:
+  - src
+exclude:
+  - src/generated/**
+
+rules:
+  - name: ...
+```
+
+- **No `include` or `exclude`** — All `.py` files under the project root are scanned
+- **`include` only** — Only files matching the given paths are scanned
+- **`exclude` only** — All files except those matching the given paths are scanned
+- **Both** — `include` is applied first, then `exclude` filters within that result
+
+### Wildcard
+
+`*` matches a single level in dotted module paths:
+
+```yaml
+modules: contexts.*.domain  # matches contexts.boards.domain, contexts.auth.domain, ...
+```
+
+`**` matches one or more levels:
+
+```yaml
+modules: contexts.**.domain  # matches contexts.boards.domain, contexts.boards.sub.domain, ...
+```
+
+### Named Capture
+
+`{name}` captures a single level (like `*`) and allows back-referencing:
+
+```yaml
+apply:
+  - name: domain-isolation
+    rules: [attribute-matches-type]
+    modules: contexts.{context}.domain
+```
+
+### pyproject.toml
+
+You can also configure in `pyproject.toml`:
+
+```toml
+[[tool.python-naming-linter.rules]]
+name = "bool-method-prefix"
+type = "function"
+
+[tool.python-naming-linter.rules.filter]
+return_type = "bool"
+
+[tool.python-naming-linter.rules.naming]
+prefix = ["is_", "has_", "should_"]
+
+[[tool.python-naming-linter.apply]]
+name = "all"
+rules = ["bool-method-prefix"]
+modules = "**"
+```
+
+## CLI
+
+```bash
+# Check with auto-discovered config (searches upward from cwd)
+pnl check
+
+# Specify config file (project root = config file's parent directory)
+pnl check --config path/to/config.yaml
+```
+
+Exit codes:
+
+- `0` — No violations
+- `1` — Violations found
+- `2` — Config file not found
+
+If no `--config` is given, the tool searches upward from the current directory for `.python-naming-linter.yaml` or `pyproject.toml` (with `[tool.python-naming-linter]`). The config file's parent directory is used as the project root.
+
+## Pre-commit
+
+Add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/heumsi/python-naming-linter
+  rev: ''  # Use the tag you want to point at (e.g., v0.1.0)
+  hooks:
+    - id: python-naming-linter
+```
+
+To pass custom options:
+
+```yaml
+- repo: https://github.com/heumsi/python-naming-linter
+  rev: ''
+  hooks:
+    - id: python-naming-linter
+      args: [--config, custom-config.yaml]
+```
+
+## License
+
+MIT