Initial commit

2025-11-30 08:30:04 +08:00
commit 833eac73ea
20 changed files with 2939 additions and 0 deletions
--- a/skills/python-project-setup/project-structure-template.md
+++ b/skills/python-project-setup/project-structure-template.md
@@ -0,0 +1,112 @@
+# Python Project Structure Template
+
+## Standard Directory Layout
+
+```
+project_name/
+├── .vscode/                    # VSCode editor configuration
+│   ├── settings.json          # Python, ruff, mypy settings
+│   └── launch.json            # Debug configurations
+├── src/                       # Source code directory
+│   └── project_name/          # Main package (use underscores)
+│       ├── __init__.py        # Package initialization
+│       ├── main.py            # Entry point (if applicable)
+│       ├── models/            # Data models (Pydantic)
+│       ├── services/          # Business logic
+│       ├── api/               # API routes (if using FastAPI)
+│       └── utils/             # Utility functions
+├── tests/                     # Test directory
+│   ├── __init__.py
+│   ├── conftest.py            # Pytest fixtures
+│   ├── test_main.py           # Test files (prefix with test_)
+│   └── integration/           # Integration tests
+├── docs/                      # Documentation
+│   ├── index.md
+│   └── api/                   # API documentation
+├── .github/                   # GitHub configuration
+│   ├── workflows/             # CI/CD workflows
+│   │   └── test.yml
+│   └── dependabot.yml         # Dependency updates
+├── .gitignore                 # Git ignore patterns
+├── .python-version            # Python version for pyenv
+├── pyproject.toml             # Project metadata and dependencies
+├── README.md                  # Project documentation
+└── uv.lock                    # Locked dependencies (generated)
+```
+
+## File Naming Conventions
+
+- **Python packages**: Use underscores (e.g., `my_package`)
+- **Project names**: Use underscores (e.g., `my_project`)
+- **Test files**: Prefix with `test_` (e.g., `test_models.py`)
+- **Private modules**: Prefix with `_` (e.g., `_internal.py`)
+
+## Directory Purpose
+
+### `src/project_name/`
+Main application code organized by function:
+- `models/` - Data classes, Pydantic models, database models
+- `services/` - Business logic and service layer
+- `api/` - API endpoints and route handlers (FastAPI)
+- `utils/` - Helper functions and utilities
+- `config/` - Configuration management
+
+### `tests/`
+Test files mirroring the structure of `src/`:
+- Unit tests for each module
+- Integration tests in `integration/` subdirectory
+- `conftest.py` for shared fixtures
+- Use pytest conventions
+
+### `docs/`
+Project documentation:
+- User guides
+- API documentation
+- Architecture decisions
+- Setup instructions
+
+## Module Organization
+
+Each Python module should follow this pattern:
+
+```python
+# frozen_string_literal equivalent in Python
+"""Module docstring describing purpose."""
+
+from typing import Any, Optional
+
+import third_party_package
+
+from project_name import local_module
+
+
+class MyClass:
+    """Class docstring."""
+
+    def __init__(self, param: str) -> None:
+        """Initialize with param."""
+        self.param = param
+
+    def method(self) -> str:
+        """Method docstring."""
+        return self.param
+
+
+def public_function() -> None:
+    """Public function docstring."""
+    pass
+
+
+def _private_function() -> None:
+    """Private helper function."""
+    pass
+```
+
+## Best Practices
+
+1. **Use `src/` layout**: Prevents accidental imports of local code
+2. **Type hints everywhere**: Add type annotations to all functions
+3. **Docstrings**: Document all public classes and functions
+4. **Test organization**: Mirror source structure in tests
+5. **Configuration**: Use environment variables or config files, never hardcode
+6. **Dependencies**: Separate dev dependencies from runtime dependencies