pyproject.toml

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name = "bluetooth-sig"
dynamic = ["version"]
authors = [{ name = "RonanB96", email = "RonanB96@users.noreply.github.com" }]
maintainers = [
    { name = "RonanB96", email = "RonanB96@users.noreply.github.com" },
]
description = "Pure Bluetooth SIG standards library for characteristic and service interpretation"
readme = "README.md"
license = { file = "LICENSE" }
requires-python = ">=3.10"
keywords = ["bluetooth", "bluetooth-sig", "gatt", "standards"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Communications",
    "Topic :: Software Development :: Libraries",
    "Typing :: Typed",
]
dependencies = [
    "pyyaml~=6.0.0",
    "msgspec>=0.18.0",
    "typing_extensions>=4.0.0",
    "cryptography>=44.0.0",
]

[project.urls]
documentation = "https://ronanb96.github.io/bluetooth-sig-python/"
repository = "https://github.com/RonanB96/bluetooth-sig-python"
homepage = "https://github.com/RonanB96/bluetooth-sig-python"
bugs = "https://github.com/RonanB96/bluetooth-sig-python/issues"
changelog = "https://ronanb96.github.io/bluetooth-sig-python/community/changelog.html"

[project.optional-dependencies]
# test-core: pytest framework (shared by dev, test, and release validation)
test-core = [
    "pytest>=8.4,<10.0",
    "pytest-asyncio>=0.23.0,<1.5",
    "pytest-cov>=6.2,<8",
    "nest-asyncio>=1.5.0",
    "pytest-benchmark~=5.1",
    "pytest-xdist~=3.0",
]
# ble: BLE client libraries (shared by test and examples)
ble = [
    "bleak>=0.21.0",
    "bleak-retry-connector>=2.13.1,<5",
    "simplepyble>=0.10.3",
    "bluepy>=1.3.0",
]
dev = [
    "bluetooth-sig[test-core]",
    "ruff~=0.15",
    "pydocstyle~=6.3",
    "types-PyYAML~=6.0",
    "types-requests~=2.32",
    "mypy>=1.19.0",
    "ipdb~=0.13",
    "coverage~=7.0",
]
test = [
    "bluetooth-sig[test-core,ble]",
    "pytest-markdown-docs~=0.9",
    "playwright~=1.56",
    "pytest-playwright~=0.7",
    "beautifulsoup4>=4.12.0",
    "lxml>=4.9.0",
    "requests>=2.32.0",
]
examples = [
    "bluetooth-sig[ble]",
    # BLE server/peripheral library for encoding examples
    "bless>=0.3.0",
]
docs = [
    "sphinx>=7.2.0",
    "sphinx-autoapi>=3.0.0",
    "sphinx-autobuild>=2024.2.4",
    "myst-parser>=2.0.0",
    "sphinx-design>=0.5.0",
    "furo>=2024.1.29",
    "git-changelog~=2.7",
    "sphinxcontrib-mermaid>=0.9.0",
    "sphinx-copybutton>=0.5.0",
    "linkify-it-py>=2.0.0",
    "pymdown-extensions>=10.0.0",
    "pydeps>=1.12.0",
    "pylint>=3.0.0", # For pyreverse docs generation
]

[project.scripts]
# Note: No CLI scripts for this library package
# bluetooth_sig_python = "bluetooth_sig_python.cli:app"

[tool.pytest.ini_options]
asyncio_mode = "strict"
testpaths = ["tests"]
pythonpath = ["src", "."]
addopts = "-m 'not benchmark and not built_docs and not playwright'"
norecursedirs = ["tests/benchmarks"]
markers = [
    "benchmark: marks benchmark tests (deselected by default)",
    "built_docs: marks tests that require built documentation (deselected by default)",
    "docs: Tests for documentation examples and code blocks",
    "code_blocks: Tests that execute code blocks extracted from markdown documentation",
    "playwright: Tests using Playwright for browser automation",
    "accessibility: Tests for documentation accessibility compliance",
    "packaging: Smoke tests that validate the installed package (data files, imports, core lookups)",
]

[tool.hatch.build]
exclude = ["tests/*", "scripts/*"]

[tool.hatch.build.hooks.custom]
# Custom build hook to automatically initialize git submodule
# This enables pip install from git to work without manual submodule init
path = "hatch_build.py"

[tool.hatch.version]
source = "vcs"

[tool.hatch.version.raw-options]
version_scheme = "no-guess-dev"
local_scheme = "node-and-date"

[tool.hatch.build.hooks.vcs]
version-file = "src/bluetooth_sig/_version.py"

[tool.hatch.build.targets.wheel]
packages = ["src/bluetooth_sig"]

[tool.hatch.build.targets.wheel.force-include]
"bluetooth_sig" = "bluetooth_sig/bluetooth_sig"

[tool.hatch.metadata]
allow-direct-references = true

[tool.ruff]
line-length = 120
# Allow Ruff to apply safe, automatic fixes by default when invoked without
# explicit `--no-fix`/`--fix` flags. Individual CI or developer workflows may
# still override this via the command-line.
fix = true
target-version = "py310"
exclude = [".git", "__pycache__", "build", "dist", ".venv", ".venv*", ".eggs", "src/bluetooth_sig/_version.py"]

[tool.ruff.lint]
select = [
    "E", "W", "F", "I",
    "B", "UP", "ANN", "D",
    "C4",   # comprehensions
    "SIM",  # simplify
    "A",    # builtins shadowing
    "ARG",  # unused arguments
    "PTH",  # pathlib rules
    "TRY",  # better exception handling
    "RET",  # return statements consistency
    "ERA",  # commented-out code
    "RUF",  # ruff-specific rules
    "PL",   # Pylint-compatible checks
    "N",    # pep8-naming conventions
    "G",    # flake8-logging-format
]
ignore = [
    "E701",    # Multiple statements on one line (colon)
    "E702",    # Multiple statements on one line (semicolon)
    "TRY003",  # long Exception message
    "G004",    # Logging statement uses f-string (allow f-strings in logging)
    "RUF022",  # __all__ sorting - allow grouped organization
]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"] # Ignore unused imports in __init__.py files
"src/bluetooth_sig/gatt/**/__init__.pyi" = ["F401", "PLE0604"] # Generated stubs re-export for mypy only
"src/bluetooth_sig/gatt/**/_export_map.py" = ["E501"] # Generated lazy export maps with long module paths
"src/bluetooth_sig/gatt/characteristics/__init__.py" = ["F401", "PLE0604"]
"src/bluetooth_sig/gatt/services/__init__.py" = ["F401", "PLE0604"]
"src/bluetooth_sig/gatt/descriptors/__init__.py" = ["F401", "PLE0604"]
# Tests and examples intentionally omit exhaustive Google-style docstrings in
# many places (fixtures, local test helpers, and example scripts). Ignore
# docstring-related (D...) codes in those paths so we can focus fixes on
# production code under `src/`.
"tests/**" = [
    "PLC0415", # Allow lazy imports for test dependencies
    "PLR2004", # Allow magic numbers in test data
    "ARG001", "ARG002", "ARG003", "ARG004", "ARG005",  # Allow all unused arguments in tests
    "D100", "D101", "D102", "D103", "D104", "D105", "D107", "D205", "D401", "D417",  # Docstring rules
    "F811",    # Pytest fixtures trigger redefinition warnings
    "ANN401",  # pytest-benchmark doesn't have type stubs
    "PTH123",  # Allow builtin open() in tests
    "RUF043",  # Allow regex patterns without escaping in pytest.raises
    "SIM102", "SIM108", "SIM118",  # Allow various code patterns in tests
    "RET504",  # Allow unnecessary variable assignment before return
    "TRY300",  # Allow statements in try blocks
]
"examples/**" = [
    "PLR0912", "PLR0913", "PLR0915",  # Allow complex demo code
    "PLC0415",  # Allow lazy imports for optional dependencies
    "PTH100", "PTH118", "PTH120",  # Allow os.path for compatibility examples
    "TRY300", "TRY301",  # Allow various exception patterns
    "SIM105", "SIM118",  # Allow various code simplifications
    "RUF001", "RUF006", "RUF015",  # Allow various patterns
    "N806", "ARG001",  # Allow naming and unused args
    "D100", "D101", "D102", "D103", "D104", "D105", "D107", "D205", "D401", "D417",  # Docstrings
]
"src/bluetooth_sig/gatt/characteristics/**" = [
    "ARG002",  # Characteristics implement common interface - unused params are expected
]

[tool.ruff.lint.pylint]
# Pylint-specific settings for PL rules - adjusted for complex parsing logic
max-args = 10          # Protocol implementations may need many parameters
max-branches = 25      # Parsing functions need complex branching for protocol variants
max-returns = 10       # Protocol parsers have multiple valid exit points
max-statements = 100   # Protocol parsing functions can be legitimately long

[tool.ruff.lint.pep8-naming]
# Allow specific short variable names that are conventional in BLE/math contexts
classmethod-decorators = ["classmethod"]
extend-ignore-names = ["id", "i", "j", "k", "ex", "Run", "_", "fp", "e"]

[tool.ruff.lint.pydocstyle]
# Make Ruff's pydocstyle plugin use the same Google convention the project
# already declares for the standalone `pydocstyle` tool. This prevents Ruff
# from enabling incompatible pydocstyle rules and eliminates the spurious
# "incompatible rules" warnings that were previously reported during
# formatting/lint runs.
convention = "google"

[tool.ruff.format]
# Use black-compatible formatting
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
# Reformat python code examples found inside docstrings. This allows Ruff to
# automatically tidy up code fences and doctest examples inside docstrings.
docstring-code-format = true

[tool.ruff.lint.isort]
known-first-party = ["bluetooth_sig"]
force-single-line = false

[tool.mypy]
# Strict mode configuration for Bluetooth SIG Python library
python_version = "3.10"  # Enable modern union syntax (X | Y)
strict = true

# Fix module path conflicts in editable installs
# mypy_path = "src:stubs"
explicit_package_bases = true

# Additional strict checks
disallow_any_generics = true
disallow_any_unimported = true
disallow_incomplete_defs = true
disallow_subclassing_any = true
disallow_untyped_calls = true
disallow_untyped_decorators = true
disallow_untyped_defs = true
warn_redundant_casts = true
warn_return_any = true
warn_unreachable = true
warn_unused_configs = true
warn_unused_ignores = true
show_error_codes = true

# Use package-based checking so mypy maps modules consistently for a src/ layout.
# This is the documented approach to avoid "Source file found twice" issues
# when the environment or installed packages expose sources under multiple roots.
packages = ["bluetooth_sig"]

# Keep explicit package bases to help mypy resolve namespace packages in src/

# Allow some flexibility for certain patterns
allow_redefinition = true
check_untyped_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
# Allow some flexibility for mock objects and fixtures
disallow_untyped_defs = true
disallow_incomplete_defs = true
warn_unused_ignores = false  # Allow extra type: ignore comments for test flexibility
ignore_missing_imports = true  # Allow missing imports for test utilities
disallow_any_unimported = false  # Allow untyped imports in tests (e.g., playwright)

[[tool.mypy.overrides]]
module = "examples.*"
disallow_untyped_defs = true
disallow_incomplete_defs = true
warn_unused_ignores = false  # Allow extra type: ignore comments for flexibility
disallow_any_unimported = false  # Allow untyped optional dependencies in examples

[[tool.mypy.overrides]]
module = "examples.backups.*"
ignore_errors = true  # Old backup files - not part of active codebase

[[tool.mypy.overrides]]
module = "pydantic.*"
# Optional dependency
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "simplepyble.*"
# Simplepyble is an optional external dependency used in examples; it does not ship
# type stubs. Allow missing imports for it so example code mypy checks do not fail.
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "bluepy.*"
# BluePy is an optional external dependency used in examples; it does not ship
# type stubs or py.typed marker. Allow mypy to treat it as untyped and disable
# strict checks that would fail due to untyped imports.
ignore_missing_imports = true
disallow_any_unimported = false

[[tool.mypy.overrides]]
module = "playwright.*"
# Playwright is an optional dependency for documentation tests.
# It has inline types but mypy has issues finding them in editable installs.
ignore_missing_imports = true
disallow_any_unimported = false

[tool.pydocstyle]
# Enforce Google-style docstrings as mandated by project standards
convention = "google"
# Prevent inheriting a parent pydocstyle config which could change the
# effective set of checked codes; keep the repository config deterministic.
inherit = false
# D202: No blank lines allowed after function docstring - conflicts with Black
# formatter when there are nested functions (Black requires blank line)
add-ignore = ["D202"]

[tool.git-changelog]
# Auto-generated changelog from conventional commits
# https://pawamoy.github.io/git-changelog/usage/
convention = "conventional"
output = "docs/source/community/changelog.md"
provider = "github"
template = "keepachangelog"
sections = "feat,fix,doc,docs,perf,refactor,test,ci,build,chore,revert,deps,style"
include-all = true
versioning = "semver"
zerover = true