python-dependency-linter 0.1.0__tar.gz → 0.3.0__tar.gz

python_dependency_linter-0.3.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_dependency_linter-0.3.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_dependency_linter-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Create a config file with ...
+        2. Run `pdl check`
+        3. See error ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Configuration
+      description: Your `.python-dependency-linter.yaml` (remove sensitive info).
+      render: yaml
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Please provide the following info.
+      value: |
+        - OS:
+        - Python version:
+        - python-dependency-linter version:
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output / logs
+      description: Paste any relevant CLI output.
+      render: shell

python_dependency_linter-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / Discussion
+    url: https://github.com/heumsi/python-layer-dependency-linter/discussions
+    about: Ask questions or start a discussion here.

python_dependency_linter-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe your idea below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve? What's missing?
+      placeholder: "e.g., I want to allow wildcard patterns in third_party rules, but currently ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you think this should work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context, examples, or config snippets.

python_dependency_linter-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,27 @@
+<!--
+  ⚠️ PR Title Convention
+  PRs are squash merged, so the PR title becomes the final commit message.
+  Please use the following format:
+
+    <gitmoji> <type>: <Description>
+
+  Examples:
+    ✨ feat: Add support for relative imports
+    🐛 fix: Use exit code 2 for config file not found
+
+  See CONTRIBUTING.md for the full list of types.
+-->
+
+## What does this PR do?
+
+<!-- A brief description of the change. -->
+
+## Related issue
+
+<!-- Link to the issue this PR addresses, e.g., Closes #123 -->
+
+## Checklist
+
+- [ ] Tests added / updated
+- [ ] `pdl check` runs without errors on the example config
+- [ ] Documentation updated (if applicable)

{python_dependency_linter-0.1.0 → python_dependency_linter-0.3.0}/.github/workflows/ci.yaml

@@ -3,14 +3,18 @@ name: CI
 on:
   pull_request:
     branches: [main]
+    paths:
+      - "python_dependency_linter/**"
+      - "tests/**"
+      - "pyproject.toml"
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: astral-sh/setup-uv@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
       - run: uv pip install --system -e ".[dev]"
@@ -23,9 +27,9 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: astral-sh/setup-uv@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv pip install --system -e ".[dev]"

{python_dependency_linter-0.1.0 → python_dependency_linter-0.3.0}/.github/workflows/publish.yaml

@@ -11,13 +11,13 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Generate full changelog
         uses: orhun/git-cliff-action@v4
         with:
-          config: cliff.toml
+          config: pyproject.toml
           args: --verbose
         env:
           OUTPUT: CHANGELOG.md
@@ -33,7 +33,7 @@ jobs:
         id: release_notes
         uses: orhun/git-cliff-action@v4
         with:
-          config: cliff.toml
+          config: pyproject.toml
           args: --verbose --latest --strip header
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -50,7 +50,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v5
         with:
           python-version: "3.13"

python_dependency_linter-0.3.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-03-30
+
+### Documentation
+
+- Remove design spec and implementation plan docs
+- Add GitHub issue and PR templates
+- Add example for omitted category behavior in allow rules
+- Add architecture examples to README
+- Add pre-commit hook custom options example
+- Expand pyproject.toml examples with multiple rules and deny
+- Add "What It Does" section to README
+
+### Features
+
+- Support `**` glob pattern for matching nested submodules (#6)
+- Add undocumented features to README
+
+### Miscellaneous
+
+- Use hatch-vcs for dynamic versioning from git tags
+- Add gitmoji preprocessor to git-cliff config
+- Move git-cliff config from cliff.toml to pyproject.toml
+- Skip CHANGELOG update commits in git-cliff output
+
+### Testing
+
+- Limit CI to source and test file changes
+
+### Build
+
+- Bump actions/checkout from 4 to 6 (#3)
+- Bump actions/setup-python from 5 to 6 (#2)
+## [0.1.0] - 2026-03-30
+
+### Bug Fixes
+
+- Add isort config and fix plan typo
+- Add tomli fallback for Python 3.10 compatibility
+- Add import content to fixture files
+
+### CI/CD
+
+- Add GitHub Actions for CI, PyPI publish, and Dependabot
+- Add git-cliff changelog generation on release
+- Add GitHub Release creation on tag
+
+### Documentation
+
+- Add design spec for python-dependency-linter
+- Add implementation plan
+- Add README
+- Add MIT LICENSE
+
+### Features
+
+- Add config loading for YAML and pyproject.toml
+- Add AST-based import parser
+- Add import resolver for classification
+- Add wildcard matcher and rule merging
+- Add dependency checker with allow/deny logic
+- Add violation reporter
+- Add CLI with check command
+- Add pre-commit hook definition
+
+### Miscellaneous
+
+- Initialize project scaffolding
+- Add license, readme, and classifiers to pyproject.toml
+- Add .gitignore

python_dependency_linter-0.3.0/CLAUDE.md

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

python_dependency_linter-0.3.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/) with [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
+
+```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_dependency_linter-0.1.0 → python_dependency_linter-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-dependency-linter
-Version: 0.1.0
+Version: 0.3.0
 Summary: A dependency linter for Python projects
 License-Expression: MIT
 License-File: LICENSE
@@ -27,6 +27,14 @@ Description-Content-Type: text/markdown
 
 A dependency linter for Python projects. Define rules for which modules can depend on what, and catch violations.
 
+## What It Does
+
+- Define dependency rules between modules using a simple YAML or TOML config
+- Detect imports that violate your rules with a single CLI command
+- Integrate into CI or pre-commit to keep your architecture consistent
+
+For Python developers who care about module boundaries and dependency direction — whether you're applying Layered, Hexagonal, Clean Architecture, or your own conventions.
+
 ## Installation
 
 ```bash
@@ -80,8 +88,95 @@ contexts/boards/domain/models.py:9
 Found 2 violation(s).
 ```
 
+## Examples
+
+### Layered Architecture
+
+Enforce dependency direction: `presentation → application → domain`, where `domain` has no outward dependencies.
+
+```yaml
+rules:
+  - name: domain-isolation
+    modules: my_app.domain
+    allow:
+      standard_library: ["*"]
+      third_party: []
+      local: [my_app.domain]
+
+  - name: application-layer
+    modules: my_app.application
+    allow:
+      standard_library: ["*"]
+      third_party: [pydantic]
+      local:
+        - my_app.application
+        - my_app.domain
+
+  - name: presentation-layer
+    modules: my_app.presentation
+    allow:
+      standard_library: ["*"]
+      third_party: [fastapi, pydantic]
+      local:
+        - my_app.presentation
+        - my_app.application
+        - my_app.domain
+```
+
+### Hexagonal Architecture
+
+Isolate domain from infrastructure. Ports (interfaces) live in domain, adapters depend on domain but not vice versa.
+
+```yaml
+rules:
+  - name: domain-no-infra
+    modules: contexts.*.domain
+    allow:
+      standard_library: [dataclasses, typing, abc]
+      third_party: []
+      local: [contexts.*.domain]
+
+  - name: adapters-depend-on-domain
+    modules: contexts.*.adapters
+    allow:
+      standard_library: ["*"]
+      third_party: ["*"]
+      local:
+        - contexts.*.adapters
+        - contexts.*.domain
+```
+
 ## Configuration
 
+### Include / Exclude
+
+Control which files are scanned using `include` and `exclude`:
+
+```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
+
+Bare directory names (e.g., `src`) and trailing-slash forms (e.g., `src/`) are treated the same as `src/**`.
+
+In `pyproject.toml`:
+
+```toml
+[tool.python-dependency-linter]
+include = ["src"]
+exclude = ["src/generated/**"]
+```
+
 ### Rule Structure
 
 Each rule has:
@@ -111,13 +206,25 @@ Dependencies are classified into three categories (per PEP 8):
 - `third_party` — Installed packages (`pydantic`, `sqlalchemy`, ...)
 - `local` — Modules in your project
 
+Both absolute imports (`from contexts.boards.domain import models`) and relative imports (`from ..domain import models`) are analyzed. Relative imports are resolved to absolute module names based on the file's location.
+
 ### Behavior
 
 - **No rule** — Everything is allowed
 - **`allow` only** — Whitelist mode. Only listed dependencies are allowed
 - **`deny` only** — Blacklist mode. Listed dependencies are denied, rest allowed
 - **`allow` + `deny`** — Allow first, then deny removes exceptions
-- If `allow` exists but a category is omitted, that category allows all
+- If `allow` exists but a category is omitted, that category allows all. For example:
+
+```yaml
+rules:
+  - name: domain-isolation
+    modules: contexts.*.domain
+    allow:
+      third_party: [pydantic]
+      local: [contexts.*.domain]
+      # standard_library is omitted → all standard library imports are allowed
+```
 
 Use `"*"` to allow all within a category:
 
@@ -134,6 +241,23 @@ allow:
 modules: contexts.*.domain  # matches contexts.boards.domain, contexts.auth.domain, ...
 ```
 
+`**` matches one or more levels in dotted module paths:
+
+```yaml
+modules: contexts.**.domain  # matches contexts.boards.domain, contexts.boards.sub.domain, ...
+```
+
+### Submodule Matching
+
+When a pattern is used in `allow` or `deny`, it also matches submodules of the matched module. For example:
+
+```yaml
+allow:
+  local: [contexts.*.domain]
+```
+
+This allows imports of `contexts.boards.domain` as well as its submodules like `contexts.boards.domain.models` or `contexts.boards.domain.entities.metric`.
+
 ### Rule Merging
 
 When multiple rules match a module, they are merged. Specific rules override wildcard rules per field:
@@ -164,6 +288,22 @@ modules = "contexts.*.domain"
 standard_library = ["dataclasses", "typing"]
 third_party = ["pydantic"]
 local = ["contexts.*.domain"]
+
+[[tool.python-dependency-linter.rules]]
+name = "application-dependency"
+modules = "contexts.*.application"
+
+[tool.python-dependency-linter.rules.allow]
+standard_library = ["*"]
+third_party = ["pydantic"]
+local = ["contexts.*.application", "contexts.*.domain"]
+
+[[tool.python-dependency-linter.rules]]
+name = "no-boto-in-domain"
+modules = "contexts.*.domain"
+
+[tool.python-dependency-linter.rules.deny]
+third_party = ["boto3"]
 ```
 
 ## CLI
@@ -183,6 +323,13 @@ Exit codes:
 
 - `0` — No violations
 - `1` — Violations found
+- `2` — Config file not found
+
+If no `--config` is given, the tool looks for `.python-dependency-linter.yaml` in the current directory. If the config file does not exist, the tool prints an error and exits with code `2`:
+
+```
+Error: Config file not found: .python-dependency-linter.yaml
+```
 
 ## Pre-commit
 
@@ -195,6 +342,16 @@ Add to `.pre-commit-config.yaml`:
     - id: python-dependency-linter
 ```
 
+To pass custom options (e.g., a different config file or project root):
+
+```yaml
+- repo: https://github.com/heumsi/python-dependency-linter
+  rev: v0.1.0
+  hooks:
+    - id: python-dependency-linter
+      args: [--config, custom-config.yaml, --project-root, src]
+```
+
 ## License
 
 MIT