or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-backend.mdbuilders.mdconfiguration.mdconstraints.mdfactory-core.mdindex.mdjson-validation.mdpackages.mdutilities.mdvcs-support.mdversion-system.md
tile.json

tessl/pypi-poetry-core

Poetry PEP 517 Build Backend for building Python packages with lightweight, compliant, self-contained build system

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/poetry-core@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-poetry-core@2.1.0

index.mddocs/

poetry-core

Poetry Core is a PEP 517 build backend implementation developed for Poetry. It provides a lightweight, fully compliant, self-contained package allowing PEP 517-compatible build frontends to build Poetry-managed projects.

Package Information

  • Package Name: poetry-core
  • Package Type: PyPI
  • Language: Python
  • Version: 2.1.3
  • Installation: pip install poetry-core
  • Main Package: poetry.core
  • Build Backend: poetry.core.masonry.api

Core Imports

# Version information
from poetry.core import __version__

# Factory for creating Poetry instances
from poetry.core.factory import Factory

# Main Poetry class
from poetry.core.poetry import Poetry

# Version constraints
from poetry.core.constraints.version import (
    Version, VersionConstraint, VersionRange, VersionUnion, 
    EmptyConstraint as VersionEmptyConstraint,
    parse_constraint, parse_marker_version_constraint
)

# Generic constraints  
from poetry.core.constraints.generic import (
    BaseConstraint, Constraint, AnyConstraint, EmptyConstraint,
    MultiConstraint, UnionConstraint, 
    parse_constraint as parse_generic_constraint,
    parse_extra_constraint
)

# Package types
from poetry.core.packages.dependency import Dependency
from poetry.core.packages.package import Package  
from poetry.core.packages.project_package import ProjectPackage
from poetry.core.packages.specification import PackageSpecification
from poetry.core.packages.dependency_group import DependencyGroup, MAIN_GROUP

# Dependency types
from poetry.core.packages.directory_dependency import DirectoryDependency
from poetry.core.packages.file_dependency import FileDependency
from poetry.core.packages.url_dependency import URLDependency
from poetry.core.packages.vcs_dependency import VCSDependency

# Version and markers
from poetry.core.version.pep440 import PEP440Version, Release, ReleaseTag, LocalSegmentType
from poetry.core.version.markers import (
    BaseMarker, AnyMarker, EmptyMarker, SingleMarker, MultiMarker, MarkerUnion,
    parse_marker, intersection, union
)
from poetry.core.version.helpers import format_python_constraint, PYTHON_VERSION

# Configuration
from poetry.core.pyproject.toml import PyProjectTOML
from poetry.core.pyproject.tables import BuildSystem

# Builders
from poetry.core.masonry.builders.wheel import WheelBuilder
from poetry.core.masonry.builders.sdist import SdistBuilder
from poetry.core.masonry.builders.builder import Builder

# VCS Support
from poetry.core.vcs import get_vcs
from poetry.core.vcs.git import Git

# JSON Schema Validation
from poetry.core.json import validate_object, ValidationError

# SPDX License Support
from poetry.core.spdx.license import License
from poetry.core.spdx.helpers import license_by_id

# Exceptions
from poetry.core.exceptions import PoetryCoreError

Basic Usage

Creating a Poetry Project Instance

from pathlib import Path
from poetry.core.factory import Factory

# Create Poetry instance from current directory
factory = Factory()
poetry = factory.create_poetry()

# Create from specific path
poetry = factory.create_poetry(Path("/path/to/project"))

# Get package information
package = poetry.package
print(f"Package: {package.name} v{package.version}")
print(f"Description: {package.description}")

Working with Dependencies

from poetry.core.packages.dependency import Dependency
from poetry.core.constraints.version import parse_constraint

# Create a simple dependency
dep = Dependency("requests", parse_constraint("^2.25.0"))

# Create from PEP 508 string
dep = Dependency.create_from_pep_508("requests>=2.25.0,<3.0.0")

# Check dependency properties
print(f"Name: {dep.name}")
print(f"Constraint: {dep.constraint}")
print(f"Optional: {dep.optional}")

Capabilities

Poetry Core provides 10 major functional areas for building and managing Python packages:

1. PEP 517 Build Backend

Complete PEP 517 compliant build backend for building wheels and source distributions. Provides all required entry points for modern Python packaging tools.

Key APIs: get_requires_for_build_wheel, build_wheel, build_sdist, build_editable

Build Backend API →

2. Factory and Core Poetry

Central orchestration through the Factory class for creating Poetry instances and managing project configuration. The Poetry class represents a complete project context.

Key APIs: Factory.create_poetry, Factory.get_package, Poetry.package, Poetry.pyproject

Factory and Core →

3. Version Constraints

Comprehensive version constraint system supporting PEP 440 version specifications, ranges, unions, and complex constraint operations.

Key APIs: parse_constraint, Version, VersionRange, VersionUnion, EmptyConstraint

Version Constraints →

4. Package System

Complete package specification system including dependencies, project packages, and various dependency types (VCS, file, directory, URL).

Key APIs: PackageSpecification, Dependency, Package, ProjectPackage, dependency types

Package System →

5. PEP 440 Version and Markers

Full PEP 440 version implementation with environment marker support for conditional dependencies and platform-specific requirements.

Key APIs: PEP440Version, parse_marker, BaseMarker, SingleMarker, MultiMarker

Version System →

6. PyProject Configuration

Robust pyproject.toml parsing and management with full Poetry configuration support and build system handling.

Key APIs: PyProjectTOML, BuildSystem, configuration validation

Configuration →

7. Package Builders

Modern package building system supporting wheels, source distributions, and editable installs with metadata generation.

Key APIs: WheelBuilder, SdistBuilder, Builder.build, metadata preparation

Builders →

8. VCS Support

Version control system integration for handling Git repositories and dependency sources from VCS.

Key APIs: get_vcs, Git, VCS dependency handling

VCS Support →

9. JSON Schema Validation

Comprehensive JSON schema validation for Poetry configuration files and internal data structures.

Key APIs: validate_object, ValidationError, schema validation

JSON Schema Validation →

10. Utilities and Validation

Helper functions, SPDX license handling, version formatting, and various utility functions for package management.

Key APIs: license_by_id, format_python_constraint, readme_content_type, helpers

Utilities →

Type Definitions

Core Types

from typing import Any, Mapping, Union, Iterable
from pathlib import Path

# Common constraint types
DependencyConstraint = Union[str, Mapping[str, Any]]
DependencyConfig = Mapping[str, Union[list[DependencyConstraint], DependencyConstraint]]

# Package naming types  
NormalizedName = str  # From packaging.utils
DistributionName = str

# Version types
LocalSegmentType = Union[int, str]

# Configuration types
ConfigDict = dict[str, Any]
TomlData = dict[str, Any]

# Build types
BuildIncludeFile = Any  # Internal build file representation
MetadataPath = Path
``` { .api }

### Exception Types

```python { .api }
# Base exception
class PoetryCoreError(Exception):
    """Base exception for all Poetry Core errors"""

# Version and constraint exceptions  
class InvalidVersionError(ValueError):
    """Invalid version format"""

class ParseConstraintError(ValueError):
    """Constraint parsing error"""

# Marker and requirement exceptions
class InvalidMarkerError(ValueError):  
    """Invalid PEP 508 marker"""

class UndefinedComparisonError(ValueError):
    """Undefined comparison in marker"""

class UndefinedEnvironmentNameError(ValueError):
    """Undefined environment name in marker"""

class InvalidRequirementError(ValueError):
    """Invalid requirement specification"""

# Configuration exceptions
class PyProjectError(PoetryCoreError):
    """PyProject configuration error"""

# JSON schema validation
class ValidationError(ValueError):
    """JSON schema validation error"""

# VCS exceptions
class GitError(RuntimeError):
    """Git operation errors"""

# Module/package discovery
class ModuleOrPackageNotFoundError(ValueError):
    """Module or package not found during discovery"""

Dependency Group Constants

# Dependency group identifiers
MAIN_GROUP = "main"  # Main dependency group

Common Patterns

Building Packages Programmatically

from pathlib import Path
from poetry.core.factory import Factory
from poetry.core.masonry.builders.wheel import WheelBuilder
from poetry.core.masonry.builders.sdist import SdistBuilder

# Create Poetry instance
poetry = Factory().create_poetry(Path("/path/to/project"))

# Build wheel
wheel_path = WheelBuilder.make_in(
    poetry, 
    Path("./dist"),
    config_settings={"--build-option": ["--plat-name", "linux_x86_64"]}
)

# Build source distribution
sdist_builder = SdistBuilder(poetry)
sdist_path = sdist_builder.build(Path("./dist"))

Working with Version Constraints

from poetry.core.constraints.version import parse_constraint, Version

# Parse various constraint formats
constraint1 = parse_constraint(">=1.2.0,<2.0.0")
constraint2 = parse_constraint("^1.5.0")  # Poetry caret syntax
constraint3 = parse_constraint("~1.5.2")  # Tilde syntax

# Check version satisfaction
version = Version.parse("1.6.3")
print(constraint1.allows(version))  # True
print(constraint2.allows(version))  # True

# Combine constraints
intersection = constraint1.intersect(constraint2)
union = constraint1.union(constraint3)

Parsing Project Configuration

from pathlib import Path
from poetry.core.pyproject.toml import PyProjectTOML
from poetry.core.factory import Factory

# Load project configuration
pyproject_path = Path("pyproject.toml")
pyproject = PyProjectTOML(pyproject_path)

# Access Poetry configuration
poetry_config = pyproject.poetry_config
build_system = pyproject.build_system

# Validate configuration
errors = Factory.validate(pyproject.data)
if errors:
    for section, section_errors in errors.items():
        print(f"Errors in {section}: {section_errors}")

Dependencies

Poetry Core is designed to be self-contained with minimal external dependencies:

  • Python 3.8+
  • packaging - For version parsing and normalization
  • tomli (Python < 3.11) / tomllib (Python >= 3.11) - For TOML parsing
  • Internal vendored dependencies for isolated operation

Related Documentation