tessl/pypi-hatch
Modern, extensible Python project management tool with comprehensive environment and build system support
—
Pending
project-management.mddocs/
Project Management
Core project representation and manipulation capabilities including project discovery, metadata access, configuration management, and project initialization.
Capabilities
Project Class
Central class for representing and managing Python projects with metadata, configuration, and file system operations.
class Project:
"""
Represents a Python project with its configuration and metadata.
Args:
path (Path): Path to the project directory
name (str, optional): Override project name
config (optional): Configuration object
"""
def __init__(self, path: Path, *, name: str | None = None, config=None):
"""Initialize project instance."""
@classmethod
def from_config(cls, config, project: str) -> Project | None:
"""
Create project from configuration entry.
Args:
config: Root configuration object
project (str): Project name from configuration
Returns:
Project instance or None if not found
"""
@property
def root(self) -> Path | None:
"""
Project root directory containing pyproject.toml.
Returns:
Path to project root or None if not found
"""
@property
def location(self) -> Path:
"""
Current project location.
Returns:
Path to project directory
"""
@property
def metadata(self):
"""
Project metadata from pyproject.toml.
Returns:
Project metadata object with name, version, dependencies, etc.
"""
@property
def config(self):
"""
Project configuration.
Returns:
Project configuration object
"""
@property
def plugin_manager(self):
"""
Plugin manager for this project.
Returns:
PluginManager instance
"""
def find_project_root(self) -> Path | None:
"""
Find project root by searching for pyproject.toml.
Returns:
Path to project root or None if not found
"""
def ensure_cwd(self) -> Generator[Path, None, None]:
"""
Context manager ensuring commands run in project directory.
Yields:
Path: Current working directory
"""
@staticmethod
def canonicalize_name(name: str, *, strict=True) -> str:
"""
Canonicalize project name according to PEP 508.
Args:
name (str): Project name to canonicalize
strict (bool): Whether to apply strict canonicalization
Returns:
Canonicalized project name
"""
@staticmethod
def initialize(project_file_path, template_config):
"""
Initialize new project with template configuration.
Args:
project_file_path: Path to pyproject.toml
template_config: Template configuration data
"""Project Discovery
Utilities for discovering and validating Python projects in the file system.
def find_project_root(start_path: Path) -> Path | None:
"""
Find project root by searching for pyproject.toml.
Args:
start_path (Path): Starting directory for search
Returns:
Path to project root or None if not found
"""
def is_project_directory(path: Path) -> bool:
"""
Check if directory contains a valid Python project.
Args:
path (Path): Directory to check
Returns:
True if directory contains pyproject.toml
"""Project Metadata
Access and manipulation of project metadata from pyproject.toml including name, version, dependencies, and build configuration.
class ProjectMetadata:
"""Project metadata from pyproject.toml."""
@property
def name(self) -> str:
"""Project name."""
@property
def version(self) -> str:
"""Project version."""
@property
def description(self) -> str:
"""Project description."""
@property
def authors(self) -> list[str]:
"""Project authors."""
@property
def dependencies(self) -> list[str]:
"""Project dependencies."""
@property
def optional_dependencies(self) -> dict[str, list[str]]:
"""Optional dependencies by group."""
@property
def scripts(self) -> dict[str, str]:
"""Console scripts."""
@property
def entry_points(self) -> dict[str, dict[str, str]]:
"""Entry points by group."""
@property
def license(self) -> str:
"""Project license."""
@property
def readme(self) -> str:
"""README file path."""
@property
def urls(self) -> dict[str, str]:
"""Project URLs."""
@property
def classifiers(self) -> list[str]:
"""Trove classifiers."""
@property
def keywords(self) -> list[str]:
"""Project keywords."""
@property
def requires_python(self) -> str:
"""Required Python version."""Project Configuration
Access and management of hatch-specific project configuration including environments, build settings, and tool configuration.
class ProjectConfig:
"""Hatch project configuration from pyproject.toml [tool.hatch] section."""
@property
def environments(self) -> dict[str, dict]:
"""Environment configurations."""
@property
def build(self) -> dict:
"""Build configuration."""
@property
def version(self) -> dict:
"""Version configuration."""
@property
def metadata(self) -> dict:
"""Metadata configuration."""
@property
def publish(self) -> dict:
"""Publishing configuration."""
@property
def envs(self) -> dict[str, dict]:
"""Legacy environment configurations."""Project Initialization
Create and initialize new Python projects with proper structure, configuration, and template support.
def initialize_project(
location: Path,
name: str,
template: str = "default",
author: str | None = None,
email: str | None = None,
license: str = "MIT",
python_version: str = ">=3.8"
) -> Project:
"""
Initialize new Python project.
Args:
location (Path): Project directory
name (str): Project name
template (str): Template to use
author (str, optional): Author name
email (str, optional): Author email
license (str): License identifier
python_version (str): Required Python version
Returns:
Initialized Project instance
"""
def create_pyproject_toml(
location: Path,
name: str,
version: str = "0.0.1",
description: str = "",
author: str | None = None,
email: str | None = None,
license: str = "MIT",
python_version: str = ">=3.8",
dependencies: list[str] | None = None
) -> None:
"""
Create pyproject.toml file with basic configuration.
Args:
location (Path): Directory to create file in
name (str): Project name
version (str): Initial version
description (str): Project description
author (str, optional): Author name
email (str, optional): Author email
license (str): License identifier
python_version (str): Required Python version
dependencies (list[str], optional): Initial dependencies
"""Project Validation
Validate project structure, configuration, and metadata for correctness and compliance with standards.
def validate_project(project: Project) -> list[str]:
"""
Validate project configuration and structure.
Args:
project (Project): Project to validate
Returns:
List of validation errors (empty if valid)
"""
def validate_pyproject_toml(path: Path) -> list[str]:
"""
Validate pyproject.toml file format and content.
Args:
path (Path): Path to pyproject.toml file
Returns:
List of validation errors (empty if valid)
"""
def check_project_structure(project: Project) -> list[str]:
"""
Check project directory structure for standard layout.
Args:
project (Project): Project to check
Returns:
List of structure issues (empty if valid)
"""Usage Examples
Basic Project Operations
from hatch.project.core import Project
from pathlib import Path
# Create project instance
project = Project(Path("/path/to/project"))
# Check if project exists
if project.root:
print(f"Project found at: {project.root}")
print(f"Project name: {project.metadata.name}")
print(f"Project version: {project.metadata.version}")
else:
print("No project found")
# Work in project directory
with project.ensure_cwd():
# Commands here run in project directory
print(f"Working in: {Path.cwd()}")Project Configuration Access
from hatch.project.core import Project
project = Project(Path.cwd())
# Access metadata
print(f"Name: {project.metadata.name}")
print(f"Version: {project.metadata.version}")
print(f"Dependencies: {project.metadata.dependencies}")
# Access hatch configuration
config = project.config
environments = config.environments
build_config = config.build
# Check environment configuration
if "test" in environments:
test_env = environments["test"]
print(f"Test dependencies: {test_env.get('dependencies', [])}")Project Creation
from hatch.project.core import Project
from pathlib import Path
# Initialize new project
location = Path("./my-new-project")
location.mkdir(exist_ok=True)
# Create project with template
project = initialize_project(
location=location,
name="my-new-project",
author="Your Name",
email="your@email.com",
template="default"
)
print(f"Created project: {project.metadata.name}")Install with Tessl CLI
npx tessl i tessl/pypi-hatch