polish

Author: AryanKumar1401

.github/workflows/ci.yml

@@ -47,10 +47,22 @@ jobs:
         run: mypy src/importguard
 
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
+        exclude:
+          # Reduce CI time by testing fewer combinations
+          - os: macos-latest
+            python-version: "3.9"
+          - os: macos-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.9"
+          - os: windows-latest
+            python-version: "3.10"
     steps:
       - uses: actions/checkout@v4
 
@@ -72,3 +84,32 @@ jobs:
           python -m importguard check json
           python -m importguard check os --max-ms 5000
 
+      - name: Test JSON output
+        run: python -m importguard check json --json
+
+      - name: Test repeat functionality
+        run: python -m importguard check json --repeat 3 --max-ms 100
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+

.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing - no API token needed
+        # Configure at: https://pypi.org/manage/project/importguard/settings/publishing/
+

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-01
+
+### Added
+
+- **CLI**: `importguard check <module>` command with full option support
+  - `--max-ms MS` — Fail if import exceeds time budget
+  - `--ban MODULE` — Ban modules from being imported (repeatable)
+  - `--config FILE` — Load `.importguard.toml` configuration
+  - `--top N` — Show top N slowest imports
+  - `--json` — Machine-readable JSON output for CI
+  - `--quiet` — Only output on failure
+  - `--repeat K` — Run K times, report median (reduces noise)
+  - `--python PATH` — Use specific Python interpreter
+
+- **Configuration**: `.importguard.toml` support
+  - Global `max_total_ms` budget
+  - Per-module budgets via `[importguard.budgets]`
+  - Per-module banned imports via `[importguard.banned]`
+  - Auto-discovery walking up directory tree
+
+- **Python API**: `check_import()` function
+  - Returns `ImportResult` with full timing data
+  - Supports `max_ms`, `banned`, `repeat`, `python_path` parameters
+  - Accepts both `list` and `set` for banned modules
+
+- **Core Engine**
+  - Uses Python's `-X importtime` for accurate timing
+  - Wall-clock backup measurement via `time.perf_counter_ns()`
+  - Runs in isolated subprocess (no interpreter pollution)
+  - Handles import failures gracefully
+
+- **CI Integration**
+  - GitHub Actions workflow example
+  - Pre-commit hook example
+  - JSON output for machine parsing
+  - Warnings for near-budget imports
+
+- **Documentation**
+  - Comprehensive README with examples
+  - "Why Results Differ on CI?" troubleshooting guide
+  - "How to Keep Imports Fast" best practices
+
+### Technical Details
+
+- Zero runtime dependencies
+- Python 3.9+ support
+- Full type annotations (mypy strict)
+- 64+ test cases
+
+[0.1.0]: https://github.com/AryanKumar1401/importguard/releases/tag/v0.1.0
+

README.md

@@ -193,6 +193,164 @@ repos:
 
 ---
 
+## Why Results Differ on CI?
+
+Import times can vary significantly between your local machine and CI. Here's why and how to handle it:
+
+### Common Causes
+
+| Factor | Local | CI | Impact |
+|--------|-------|-----|--------|
+| **CPU** | Fast desktop/laptop | Shared VM cores | 2-5x slower |
+| **Disk** | SSD/NVMe | Network storage | Variable latency |
+| **Caching** | Warm `.pyc` files | Cold start | First run slower |
+| **Python version** | May differ | Matrix testing | Different stdlib |
+| **Dependencies** | Pinned versions | Fresh install | Version variance |
+
+### Recommendations
+
+1. **Use `--repeat 3` or `--repeat 5`** — Takes median to smooth out noise
+2. **Set CI budgets 2-3x higher** than local measurements
+3. **Use separate config sections** for CI vs local:
+
+```toml
+# .importguard.toml
+[importguard]
+max_total_ms = 200  # Local development
+
+# Override in CI with environment-specific config
+# or use: importguard check mypkg --max-ms 500
+```
+
+4. **Pin Python version** in CI to match local:
+
+```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.11.7'  # Exact version
+```
+
+5. **Warm up before measuring** (optional):
+
+```yaml
+- name: Warm up Python cache
+  run: python -c "import mypkg" || true
+
+- name: Check import performance  
+  run: importguard check mypkg --repeat 3
+```
+
+### Debugging CI Failures
+
+```bash
+# Get detailed JSON output for investigation
+importguard check mypkg --json > import-report.json
+
+# Compare top imports between local and CI
+importguard check mypkg --top 20
+```
+
+---
+
+## How to Keep Imports Fast
+
+### 1. Lazy Imports
+
+Move heavy imports inside functions that need them:
+
+```python
+# ❌ Bad: imports pandas at module load
+import pandas as pd
+
+def process_data(path):
+    return pd.read_csv(path)
+
+# ✅ Good: imports pandas only when needed
+def process_data(path):
+    import pandas as pd
+    return pd.read_csv(path)
+```
+
+### 2. Optional Dependencies
+
+Use try/except for optional heavy dependencies:
+
+```python
+# ✅ Good: graceful degradation
+try:
+    import torch
+    HAS_TORCH = True
+except ImportError:
+    HAS_TORCH = False
+
+def train_model(data):
+    if not HAS_TORCH:
+        raise ImportError("torch required: pip install mypkg[ml]")
+    # ... use torch
+```
+
+### 3. Deferred Imports with `__getattr__`
+
+For library authors, use module-level `__getattr__`:
+
+```python
+# mypkg/__init__.py
+def __getattr__(name):
+    if name == "heavy_module":
+        from . import heavy_module
+        return heavy_module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+```
+
+### 4. Split Entry Points
+
+Separate your CLI from your library:
+
+```
+mypkg/
+├── __init__.py      # Lightweight, fast to import
+├── core.py          # Core functionality
+├── cli.py           # CLI-only, can import Click/Rich
+└── optional/
+    └── ml.py        # Heavy ML dependencies
+```
+
+```toml
+# pyproject.toml
+[project.scripts]
+mypkg = "mypkg.cli:main"  # CLI imports heavy deps
+```
+
+### 5. Avoid Import Side Effects
+
+```python
+# ❌ Bad: runs on import
+config = load_config()  # Network call!
+logger = setup_logging()  # Creates files!
+
+# ✅ Good: explicit initialization
+_config = None
+def get_config():
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+```
+
+### 6. Profile Before Optimizing
+
+Use importguard to find the actual culprits:
+
+```bash
+# Find the slowest imports
+importguard check mypkg --top 20
+
+# Ban known-heavy modules from your fast path
+importguard check mypkg.cli --ban pandas --ban torch --ban tensorflow
+```
+
+---
+
 ## Python API
 
 ```python

dist/importguard-0.1.0-py3-none-any.whl

@@ -8,24 +8,42 @@ version = "0.1.0"
 description = "Measure and enforce import-time behavior in Python projects"
 readme = "README.md"
 license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Aryan Kumar" }]
+maintainers = [{ name = "Aryan Kumar" }]
 requires-python = ">=3.9"
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Build Tools",
     "Typing :: Typed",
 ]
-keywords = ["import", "performance", "timing", "cli", "ci", "testing"]
+keywords = [
+    "import",
+    "performance", 
+    "timing",
+    "cli",
+    "ci",
+    "testing",
+    "startup",
+    "cold-start",
+    "profiling",
+    "lint",
+]
 dependencies = []
 
 [project.optional-dependencies]
@@ -41,8 +59,10 @@ importguard = "importguard.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/AryanKumar1401/importguard"
+Documentation = "https://github.com/AryanKumar1401/importguard#readme"
 Repository = "https://github.com/AryanKumar1401/importguard"
 Issues = "https://github.com/AryanKumar1401/importguard/issues"
+Changelog = "https://github.com/AryanKumar1401/importguard/releases"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/importguard"]