boto3_dataclass_service

Boto3 Dataclass Service Structure Management.

It bridges the gap between installed mypy-boto3 stub packages and the generated boto3-dataclass service packages.

The module handles:

  • Service Discovery: Automatically discovers installed mypy-boto3 stub packages

  • Path Mapping: Maps between source stub files and target dataclass package files

  • Service Name Translation: Converts between AWS service names and package naming conventions

  • Stub File Location: Provides paths to various mypy-boto3 stub files (client.pyi, type_defs.pyi, literals.pyi)

  • Build Target Paths: Defines where generated dataclass files should be placed

  • Service Enumeration: Lists all available AWS services with complete stub files

Key Concepts:

  • Service Name: The AWS service identifier (e.g., “ec2”, “s3”)

  • Package Name: The Python package name (e.g., “boto3_dataclass_ec2”)

  • Stub Package: The mypy-boto3 source package (e.g., “mypy_boto3_ec2”)

  • Structure: The complete project layout for a service-specific dataclass package

class boto3_dataclass.structures.boto3_dataclass_service.Boto3DataclassServiceStructure(package_name: str)[source]

Structure manager for boto3 dataclass service packages.

This class extends PyProjectStructure to provide AWS service-specific functionality for managing the relationship between mypy-boto3 stub packages and generated boto3-dataclass packages.

The class handles the complete lifecycle of service package structure:

  • Discovering installed mypy-boto3 stub packages in site-packages

  • Mapping service names to package naming conventions

  • Providing paths to both source stub files and target dataclass files

  • Managing the project structure for individual AWS services

Naming Conventions:

  • Service name: “ec2” (AWS service identifier)

  • Package name: “boto3_dataclass_ec2” (generated package)

  • Stub package: “mypy_boto3_ec2” (source stub package)

  • Package slug: “boto3-dataclass-ec2” (PyPI/distribution name)

Path Structure:

The class manages paths for both source (mypy-boto3) and target (dataclass) files:

site-packages/mypy_boto3_ec2/          # Source stub package
├── client.pyi                         # Client interface stubs
├── type_defs.pyi                      # Type definitions
└── literals.pyi                       # Literal type definitions

build/repos/boto3_dataclass_ec2-project/  # Target package structure
├── boto3_dataclass_ec2/
│   ├── __init__.py
│   ├── type_defs.py                   # Generated from type_defs.pyi
│   └── caster.py                      # Generated from client.pyi
├── pyproject.toml
├── README.rst
└── LICENSE.txt
Parameters:

package_name – Inherited from PyProjectStructure, format: “boto3_dataclass_{service}”

Example:
>>> # Create structure for a specific service
>>> structure = Boto3DataclassServiceStructure.new("s3")
>>> structure.service_name  # "s3"
>>> structure.package_name  # "boto3_dataclass_s3"
>>>
>>> # Get paths to stub files
>>> structure.path_mypy_boto3_type_defs_pyi  # Path to mypy_boto3_s3/type_defs.pyi
>>> structure.path_mypy_boto3_client_pyi     # Path to mypy_boto3_s3/client.pyi
>>>
>>> # Get paths for generated files
>>> structure.path_boto3_dataclass_type_defs_py  # Where to write type_defs.py
>>> structure.path_boto3_dataclass_caster_py     # Where to write caster.py
classmethod new(service_name: str)[source]

Create a new service structure for the specified AWS service.

Parameters:

service_name – The AWS service name (e.g., “ec2”, “s3”, “lambda”)

Returns:

A new Boto3DataclassServiceStructure instance configured for the service

Example:
>>> structure = Boto3DataclassServiceStructure.new("ec2")
>>> structure.service_name  # "ec2"
>>> structure.package_name  # "boto3_dataclass_ec2"
property service_name: str

Extract the AWS service name from the package name.

Returns:

The AWS service name (e.g., “ec2” from “boto3_dataclass_ec2”)

property boto3_stubs_package_name: str

Get the corresponding mypy-boto3 stub package name.

Returns:

The mypy-boto3 package name (e.g., “mypy_boto3_ec2”)

property boto3_stubs_package_name_slug: str

Get the mypy-boto3 package name in slug format (with hyphens).

Returns:

The slug format package name (e.g., “mypy-boto3-ec2”)

property dir_mypy_boto3_package: Path

Get the directory path for a given package or module name.

Example: site-packages/mypy_boto3_ec2

property path_mypy_boto3_literals_pyi: Path

Get the path to the literals stub file (literals.pyi).

Example: site-packages/mypy_boto3_ec2/literals.pyi

property path_mypy_boto3_type_defs_pyi: Path

Get the path to the type definition stub file (type_defs.pyi).

Example: site-packages/mypy_boto3_ec2/type_defs.pyi

property path_mypy_boto3_client_pyi: Path

Get the path to the client stub file (client.pyi).

Example: site-packages/mypy_boto3_ec2/client.pyi

classmethod list_all() → list[Boto3DataclassServiceStructure][source]

Discover all available AWS services with complete mypy-boto3 stub packages.

Scans the site-packages directory for mypy_boto3_* packages that contain both client.pyi and type_defs.pyi stub files, indicating they are complete and suitable for dataclass generation.

Returns:

List of Boto3DataclassServiceStructure instances for each discovered service

Example:
>>> structures = Boto3DataclassServiceStructure.list_all()
>>> service_names = [struct.service_name for struct in structures]
>>> print(service_names)  # ["ec2", "s3", "lambda", "rds", ...]
property path_boto3_dataclass_type_defs_py: Path

Get the path where the generated type_defs.py file will be written.

This file contains the dataclass definitions generated from the mypy-boto3 type_defs.pyi stub file.

Returns:

Path to the target type_defs.py file

Example:

build/repos/boto3_dataclass_ec2-project/boto3_dataclass_ec2/type_defs.py

property path_boto3_dataclass_caster_py: Path

Get the path where the generated caster.py file will be written.

This file contains utility functions for converting boto3 service responses into dataclass instances, generated from the mypy-boto3 client.pyi stub file.

Returns:

Path to the target caster.py file

Example:

build/repos/boto3_dataclass_ec2-project/boto3_dataclass_ec2/caster.py