<!-- ---
!-- Timestamp: 2025-08-31 17:57:04
!-- Author: ywatanabe
!-- File: /home/ywatanabe/.dotfiles/.claude/to_claude/guidelines/python/SCITEX-19-directory-structure-for-pip-package.md
!-- --- -->


## Directory Structure for Python PIP Packages

### Modern Python Package Structure (PEP 517/518)

```
<project-root>/
├── src/                      # Source code directory
│   └── <package_name>/       # Your actual package
│       ├── __init__.py
│       ├── module1.py
│       ├── module2.py
│       └── subpackage/
│           └── __init__.py
├── tests/                    # Test files (mirrors src/ structure)
│   ├── conftest.py          # pytest configuration
│   ├── sync_tests_with_source.sh  # Auto-sync test structure with src/
│   └── <package_name>/      # Mirrors src/<package_name>/
│       ├── test_module1.py
│       ├── test_module2.py
│       └── subpackage/
│           └── test_submodule.py
├── examples/                 # Example scripts (can mirror src/ for complex packages)
│   ├── 01_filename.py
│   ├── 02_filename.py
│   └── data/                 # Example inputs (gitignored)
│   └── outputs/              # Example outputs (gitignored)
├── docs/                     # Documentation
├── .dev/                     # Temporary work (gitignored)
│   ├── experiments/
│   └── scratch/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── MANIFEST.in
└── requirements.txt
```

### Test Directory Mirroring

The `tests/` directory **MUST mirror the structure of `src/`** for consistency:

```bash
# Example mirroring:
src/
└── gpac/
    ├── __init__.py
    ├── _PAC.py
    ├── _Filters/
    │   ├── __init__.py
    │   ├── _BaseFilter.py
    │   └── _BandpassFilter.py
    └── utils/
        └── helpers.py

tests/
├── sync_tests_with_source.sh   # Auto-sync script
└── gpac/
    ├── test__PAC.py           # Note: test_ prefix
    ├── _Filters/
    │   ├── test__BaseFilter.py
    │   └── test__BandpassFilter.py
    └── utils/
        └── test_helpers.py
```

### Auto-sync Script: `sync_tests_with_source.sh`

This script automatically:
1. Creates test directory structure mirroring `src/`
2. Creates test files for all source modules
3. Preserves existing test code when updating
4. Adds source code as comments for reference
5. Moves stale test files to `.old-<timestamp>/` directories

Key features:
- Run with `-m` or `--move` to move stale test files
- Preserves your test code when syncing
- Adds pytest runner boilerplate
- Includes source code as comments at the end of each test file

### Examples Directory Structure

For complex packages, examples can also mirror the source structure:

```bash
examples/
├── sync_examples_with_source.sh  # Auto-sync script for examples
├── example_quickstart.py         # General examples
├── example_advanced.py
├── <package_name>/              # Module-specific examples (optional)
│   ├── example_module1.py
│   └── subpackage/
│       └── example_submodule.py
└── outputs/                     # All outputs go here (gitignored)
    └── <auto-generated>/        # Created by stx.io.save()
```

### Auto-sync Script: `sync_examples_with_source.sh`

This script helps create example placeholders for key modules:
1. Creates example directory structure for important modules only
2. Generates example templates with scitex conventions
3. Preserves existing example code when updating
4. Moves stale example files to `.old-<timestamp>/` directories

Key features:
- Run with `-m` or `--move` to move stale example files
- Only creates examples for key modules (not every source file)
- Templates include stx.io conventions
- Example naming: `_ModuleName.py` → `example_ModuleName.py`

### Key Points

1. **Use `pyproject.toml` ONLY** - Don't create `setup.py` unless absolutely necessary
2. **Source in `src/`** - Prevents accidental imports during development
3. **Tests MUST mirror `src/`** - Use `sync_tests_with_source.sh` to maintain
4. **Examples use scitex conventions**:
   ```python
   import scitex as stx
   
   # Save outputs to examples/outputs/<script_name>/
   sdir = stx.io.get_dirpath(__file__, "outputs")
   stx.io.save(fig, sdir / "results.png")
   ```
5. **Test file naming**: `test_<source_filename>.py` (with test_ prefix)

### Minimal pyproject.toml Template

```toml
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package"
version = "0.1.0"
authors = [{name="Your Name", email="email@example.com"}]
description = "Package description"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
dependencies = [
    "numpy>=1.19.0",
    "scitex>=1.0.0",
]

[project.urls]
Homepage = "https://github.com/username/repo"
Repository = "https://github.com/username/repo"

[tool.setuptools]
package-dir = {"" = "src"}
packages = ["your_package"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
```

### Temporal Working Space: `.dev/`
- For temporary experiments and development work
- Organize with categories:
  ```
  .dev/
  ├── experiments/        # Testing new features
  ├── benchmarks/         # Performance testing
  ├── prototypes/         # Quick prototypes
  └── scratch/           # Temporary files
  ```
- Add `.dev/` to `.gitignore`

### Important Rules
1. **NEVER create files/directories in project root** - Use predefined directories
2. **NEVER create setup.py** - Use pyproject.toml only
3. **ALWAYS use src/ layout** - Better testing and import isolation
4. **ALWAYS follow scitex conventions** in examples
5. **ALWAYS mirror src/ structure in tests/** - Use sync_tests_with_source.sh
6. **ALWAYS use test_ prefix** for test files (e.g., `test_module.py`)

### Example Directory After Following Guidelines
```
my-package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── models/
│           ├── __init__.py
│           └── base.py
├── tests/
│   ├── conftest.py
│   ├── sync_tests_with_source.sh
│   └── my_package/
│       ├── test_core.py
│       ├── test_utils.py
│       └── models/
│           └── test_base.py
├── examples/
│   ├── sync_examples_with_source.sh
│   ├── example_basic_usage.py
│   ├── my_package/          # Optional: module-specific examples
│   │   └── models/
│   │       └── example_custom_model.py
│   └── outputs/             # Created by stx.io.save()
│       └── example_basic_usage/
│           └── results.png
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore
```

### Benefits of This Structure

1. **Easy navigation** - Test location mirrors source location
2. **Automatic maintenance** - sync_tests_with_source.sh keeps structure updated
3. **Clear organization** - Examples can be general or module-specific
4. **Modern packaging** - pyproject.toml handles everything
5. **scitex integration** - Consistent output handling across examples

## Your Understanding Check
Did you understand the guideline? If yes, please say:
`CLAUDE UNDERSTOOD: <THIS FILE PATH HERE>`

<!-- EOF -->