pyproject.toml

[project]
name = "pipelex-sdk"
version = "0.59.0"
description = "The Python client for the Pipelex hosted API — the MTHDS Protocol surface plus the durable run lifecycle and the Pipelex product surface, built on the `mthds` protocol base."
authors = [{ name = "Evotis S.A.S.", email = "oss@pipelex.com" }]
maintainers = [{ name = "Pipelex staff", email = "oss@pipelex.com" }]
license = "MIT"
readme = "README.md"
requires-python = ">=3.11,<3.15"
classifiers = [
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Operating System :: OS Independent",
  "License :: OSI Approved :: MIT License",
]

dependencies = [
  "mthds==0.26.0",
  "pydantic>=2.10.6,<3.0.0",
  "typing-extensions>=4.4.0",
  "httpx>=0.23.0,<1.0.0",
]

# The `pipelex-sdk` command, which `uvx pipelex-sdk run …` runs (`docs/cli.md`). Nothing in the SDK
# imports `pipelex_sdk.cli` or `pipelex_sdk.command`, so the library never loads it.
[project.scripts]
pipelex-sdk = "pipelex_sdk.cli:main"

[project.optional-dependencies]
dev = [
  "mypy==1.19.1",
  "pyright==1.1.411",
  "pylint==4.0.4",
  "ruff==0.16.4",
  "pytest>=9.0.3",
  "pytest-mock>=3.12.0,<4.0.0",
  "pytest-sugar>=1.0.0",
  # A real Werkzeug `Headers` in the webhook tests: Flask's headers iterate as (name, value) pairs.
  "werkzeug>=3.1.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project.urls]
Homepage = "https://www.pipelex.com"
Repository = "https://github.com/Pipelex/pipelex-sdk/tree/main/python"
Documentation = "https://github.com/Pipelex/pipelex-sdk/tree/main/python"
Changelog = "https://github.com/Pipelex/pipelex-sdk/blob/main/python/CHANGELOG.md"
Issues = "https://github.com/Pipelex/pipelex-sdk/issues"

# `[tool.pytest]` is the native table pytest 9 reads (`ini_options` is its backwards-compatibility
# form, and the two together are an error). `testpaths` is the unit tree alone, so a bare `pytest`
# (and `make test` / `make agent-test` with it) never collects the live e2e legs — those are
# `make e2e-test`, which names `tests/e2e` explicitly and skips itself without credentials.
[tool.pytest]
minversion = "9.0"
testpaths = ["tests/unit"]
pythonpath = ["."]

[tool.mypy]
check_untyped_defs = true
exclude = "^.*\\.venv/.*$"
mypy_path = "."
packages = ["pipelex_sdk", "tests"]
plugins = ["pydantic.mypy"]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true

[tool.pyright]
pythonVersion = "3.11"
include = ["pipelex_sdk", "tests"]
exclude = [
  "**/__pycache__",
  ".venv",
  ".git",
  "build",
  "dist",
  "**/node_modules",
  "**/.*",
]
analyzeUnannotatedFunctions = true
deprecateTypingAliases = false
disableBytesTypePromotions = true
enableExperimentalFeatures = false
enableTypeIgnoreComments = true
extraPaths = ["./tests"]
reportAbstractUsage = "error"
reportArgumentType = "error"
reportAssertAlwaysTrue = "error"
reportAssertTypeFailure = "error"
reportAssignmentType = "error"
reportAttributeAccessIssue = "error"
reportCallInDefaultInitializer = true
reportCallIssue = "error"
reportConstantRedefinition = "error"
reportDeprecated = "error"
reportDuplicateImport = "error"
reportFunctionMemberAccess = "error"
reportGeneralTypeIssues = "error"
reportImplicitOverride = true
reportImplicitStringConcatenation = false
reportImportCycles = true
reportIncompatibleMethodOverride = "error"
reportIncompatibleVariableOverride = "error"
reportIncompleteStub = "error"
reportInconsistentConstructor = "error"
reportInconsistentOverload = "error"
reportIndexIssue = "error"
reportInvalidStringEscapeSequence = "error"
reportInvalidStubStatement = "error"
reportInvalidTypeArguments = "error"
reportInvalidTypeForm = "error"
reportInvalidTypeVarUse = "error"
reportMatchNotExhaustive = "error"
reportMissingImports = "error"
reportMissingModuleSource = "warning"
reportMissingParameterType = "error"
reportMissingSuperCall = "none"
reportMissingTypeArgument = "error"
reportMissingTypeStubs = false
reportNoOverloadImplementation = "error"
reportOperatorIssue = "error"
reportOptionalCall = "error"
reportOptionalContextManager = "error"
reportOptionalIterable = "error"
reportOptionalMemberAccess = "error"
reportOptionalOperand = "error"
reportOptionalSubscript = "error"
reportOverlappingOverload = "error"
reportPossiblyUnboundVariable = "error"
reportPrivateImportUsage = "error"
reportPrivateUsage = "error"
reportPropertyTypeMismatch = true
reportRedeclaration = "error"
reportReturnType = "error"
reportSelfClsParameterName = "error"
reportTypeCommentUsage = "error"
reportTypedDictNotRequiredAccess = "error"
reportUnboundVariable = "error"
reportUndefinedVariable = "error"
reportUninitializedInstanceVariable = "none"
reportUnknownArgumentType = "error"
reportUnknownLambdaType = "error"
reportUnknownMemberType = "error"
reportUnknownParameterType = "error"
reportUnknownVariableType = "error"
reportUnnecessaryCast = "error"
reportUnnecessaryComparison = "error"
reportUnnecessaryContains = "error"
reportUnnecessaryIsInstance = "error"
reportUnnecessaryTypeIgnoreComment = "none"
reportUnsupportedDunderAll = "error"
reportUntypedBaseClass = "error"
reportUntypedClassDecorator = "error"
reportUntypedFunctionDecorator = "error"
reportUntypedNamedTuple = "error"
reportUnusedCallResult = "none"
reportUnusedClass = "error"
reportUnusedCoroutine = "error"
reportUnusedExcept = "error"
reportUnusedExpression = "error"
reportUnusedFunction = "error"
reportUnusedImport = "none"
reportUnusedVariable = "error"
reportWildcardImportFromLibrary = "error"
strictDictionaryInference = true
strictListInference = true
strictParameterNoneValue = true
strictSetInference = true
typeCheckingMode = "strict"

# Unit tests legitimately probe internal transport/error helpers (e.g.
# _request_product, _api_response_error) before the public surface
# wraps them — allow private access in the test tree only.
[[tool.pyright.executionEnvironments]]
root = "tests"
reportPrivateUsage = "none"

[tool.ruff]
exclude = [
  ".cursor",
  ".git",
  ".github",
  ".mypy_cache",
  ".ruff_cache",
  ".venv",
  ".vscode",
]

line-length = 150
target-version = "py311"

[tool.ruff.format]

[tool.ruff.lint]
preview = true
select = ["ALL"]
ignore = [
  "missing-return-type-undocumented-public-function", # Missing return type annotation for public function `my_func`
  "missing-return-type-private-function",             # Missing return type annotation for private function `my_func`
  "missing-return-type-special-method",               # Missing return type annotation for special method `my_func`
  "missing-return-type-class-method",                 #  Missing return type annotation for classmethod `my_func`
  "any-type",                                         # Dynamically typed expressions (typing.Any) are disallowed in `...`
  "blocking-open-call-in-async-function",             # Async functions should not open files with blocking methods like `open`
  "blocking-path-method-in-async-function",           # Async functions should not use pathlib.Path methods, use trio.Path or anyio.path

  "class-as-data-structure", # Class could be dataclass or namedtuple

  "complex-structure",      # Is to complex
  "missing-trailing-comma", # Checks for the absence of trailing commas.

  "missing-copyright-notice", # Missing copyright notice at top of file

  "undocumented-public-module",       # Missing docstring in public module
  "undocumented-public-class",        # Missing docstring in public class
  "undocumented-public-method",       # Missing docstring in public method
  "undocumented-public-function",     # Missing docstring in public function
  "undocumented-public-package",      # Missing docstring in public package
  "undocumented-magic-method",        # Missing docstring in magic method
  "undocumented-public-init",         # Missing docstring in __init__
  "missing-blank-line-after-summary", # 1 blank line required between summary line and description
  "missing-trailing-period",          # First line should end with a period
  "non-imperative-mood",              # First line of docstring should be in imperative mood: "My docstring...."
  "docstring-starts-with-this",       # First word of the docstring should not be "This"
  "missing-terminal-punctuation",     # First line should end with a period, question mark, or exclamation point

  "docstring-missing-returns",      # `return` is not documented in docstring
  "docstring-extraneous-returns",   # Docstring should not have a returns section because the function doesn't return anything
  "docstring-missing-yields",       # `yield` is not documented in docstring
  "docstring-extraneous-exception", # Raised exception is not explicitly raised: `FileNotFoundError`
  "docstring-missing-exception",    # Raised exception `ModuleFileError` missing from docstring

  "call-datetime-without-tzinfo",     # `datetime.datetime()` called without a `tzinfo` argument
  "call-datetime-now-without-tzinfo", # `datetime.datetime.now()` called without a `tz` argument

  "commented-out-code", # Found commented-out code

  "boolean-type-hint-positional-argument",     # Boolean-typed positional argument in function definition
  "boolean-default-value-positional-argument", # Boolean default positional argument in function definition
  "boolean-positional-value-in-call",          #Boolean positional value in function call

  "line-contains-todo", # Line contains TODO, consider resolving the issue

  "read-whole-file", # `open` and `read` should be replaced by `Path(file_path.path).read_text(encoding="utf-8")`
  "repeated-append", # Checks for consecutive calls to append.
  "math-constant",   # Checks for literals that are similar to constants in math module.

  "log-exception-outside-except-handler", # `.exception()` call outside exception handlers

  "type-name-incorrect-variance", # `TypeVar` name "SomethingType" does not reflect its covariance; consider renaming it to "SomethingType_co"
  "compare-to-empty-string",      # Checks for comparisons to empty strings.

  "too-many-public-methods",       # Too many public methods ( > 20)
  "too-many-return-statements",    # Too many return statements (/6)
  "too-many-branches",             # Too many branches (/12)
  "too-many-arguments",            # Too many arguments in function definition (/5)
  "too-many-locals",               # Too many local variables ( /15)
  "too-many-statements",           # Too many statements (/50)
  "too-many-positional-arguments", # Too many positional arguments ( /5)
  "magic-value-comparison",        # Magic value used in comparison, consider replacing `2` with a constant variable
  "no-self-use",                   # Too many return statements in `for` loop
  "too-many-nested-blocks",        # Too many nested blocks ( > 5)

  "pytest-incorrect-pytest-import", # Incorrect import of `pytest`; use `import pytest` instead

  "os-path-abspath",  # `os.path.abspath()` should be replaced by `Path.resolve()`
  "os-makedirs",      # `os.makedirs()` should be replaced by `Path.mkdir(parents=True)`
  "os-remove",        # `os.remove()` should be replaced by `Path.unlink()`
  "os-getcwd",        # `os.getcwd()` should be replaced by `Path.cwd()`
  "os-path-join",     # `os.path.join()` should be replaced by `Path` with `/` operator
  "os-path-dirname",  # `os.path.dirname()` should be replaced by `Path.parent`
  "os-path-exists",   # `os.path.exists()` should be replaced by `Path.exists()`
  "os-path-isdir",    # `os.path.isdir()` should be replaced by `Path.is_dir()`
  "os-path-basename", # `os.path.basename()` should be replaced by `Path.name`
  "builtin-open",     # `open()` should be replaced by `Path.open()`
  "os-listdir",       # Use `pathlib.Path.iterdir()` instead.

  "redundant-literal-union", # `Literal["auto"]` is redundant in a union with `str`

  "superfluous-else-return", # superfluous-else-return

  "ambiguous-unicode-character-string",  # String contains ambiguous `′` (PRIME). Did you mean ``` (GRAVE ACCENT)?
  "ambiguous-unicode-character-comment", # Comment contains ambiguous `’` (RIGHT SINGLE QUOTATION MARK). Did you mean ``` (GRAVE ACCENT)?
  "unsorted-dunder-all",                 # Checks for __all__ definitions that are not ordered according to an "isort-style" sort.

  "suppressible-exception",          # Use `contextlib.suppress(ValueError)` instead of `try`-`except`-`pass`
  "if-else-block-instead-of-if-exp", # Use ternary operator `description = func.__doc__.strip().split("\n")[0] if func.__doc__ else func.__name__` instead of `if`-`else`-block

  "assert",                      # Use of `assert` detected
  "exec-builtin",                # Use of `exec` detected
  "hardcoded-password-func-arg", # Possible hardcoded password assigned to argument: "secret"
  "hardcoded-password-string",   # Possible hardcoded password assigned to: "child_secret"

  "suspicious-non-cryptographic-random-usage", # Cryptographically weak pseudo-random number generator

  "missing-todo-author", # Missing author in TODO; try: `# TODO(<author_name>): ...` or `# TODO @<author_name>: ...`
  "missing-todo-link",   # Missing issue link for this TODO

  "print", # `print` found

  # TODO: stop ignoring these rules
  "blind-except",                            # Do not catch blind exception: `Exception`
  "empty-method-without-abstract-decorator", # Checks for empty methods in abstract base classes without an abstract decorator.
  "non-pep604-annotation-union",             # Use `X | Y` for type annotations
  "outdated-version-block",                  # Version block is outdated for minimum Python version
  "collapsible-if",                          # Use a single `if` statement instead of nested `if` statements
  "jinja2-autoescape-false",                 # Using jinja2 templates with `autoescape=False` is dangerous and can lead to XSS. Ensure `autoescape=True` or use the `select_autoescape` function.
  "raise-within-try",                        # Abstract `raise` to an inner function
  "manual-list-comprehension",               # Use a list comprehension to create a transformed list
  "redefined-loop-name",                     # `for` loop variable `line` overwritten by assignment target
  "try-consider-else",                       # Consider moving this statement to an `else` block
  "deprecated-import",                       # `typing.List` is deprecated, use `list` instead
  "implicit-return",                         # Missing explicit `return` at the end of function able to return non-`None` value

  # Shrinking a `try` clause changes which statements its handlers cover, so satisfying
  # this rule is an error-handling refactor rather than lint cleanup. Ignored across the
  # workspace; recorded here even though this repo currently has no findings, so the
  # decision does not have to be made again by whoever writes the first long `try`.
  "too-many-statements-in-try-clause", # Try clause contains too many statements
]

[tool.ruff.lint.flake8-type-checking]
# Ruff matches only the base classes named in the class statement, so it cannot see that a model
# extending one of `mthds`'s rather than `BaseModel` directly is a pydantic model: `PipelexRunResultStart`
# and the `execute` acknowledgement in `client.py` extend `RunResultStart`, and `PipelexExecuteResult`
# extends `DictRunResultExecute`. Without these entries, an annotation such a model imports is misread as
# type-only and pushed into a `TYPE_CHECKING` block, where pydantic cannot resolve it when it builds
# the model — a runtime failure the linter would have introduced.
runtime-evaluated-base-classes = [
  "pydantic.BaseModel",
  "mthds.protocol.models.RunResultStart",
  "mthds.runners.api.models.DictRunResultExecute",
]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
  "implicit-namespace-package", # Allow test files to not have __init__.py in their directories (avoids namespace collisions)
  "private-member-access",      # Unit tests legitimately probe private transport/error helpers (e.g. _request_product, _api_response_error)
  "import-private-name",        # Unit tests legitimately import private module helpers under test (e.g. _parse_error_body)
  "unused-method-argument",     # Test-double methods match a Protocol signature; an unused param (e.g. a fake validate ignoring `render`) is intentional
  "float-equality-comparison",  # Tests assert exact float literals that round-trip exactly; `pytest.approx` would only add noise
]
"examples/**/*.py" = [
  "implicit-namespace-package", # Runnable demo scripts, not an importable package
  "print",                      # print() is the whole point of a demo script
]

[tool.uv]
required-version = ">=0.7.2"


[tool.pylint.main]
py-version = "3.11"
reports = false

[tool.pylint.messages_control]
disable = ["all"]
enable = [
  "W0101", # Unreachable code: Used when there is some code behind a "return" or "raise" statement, which will never be accessed.
  "C0103", # invalid-name (naming convention)
]
ignore = [".venv", "__pycache__", "build", "dist", ".git"]

[tool.pylint.basic]
# Variables / attributes / arguments: snake_case, not length 1
variable-rgx = "^(?!.$)[a-z_][a-z0-9_]*$"
argument-rgx = "^(?!.$)[a-z_][a-z0-9_]*$"
attr-rgx = "^(?!.$)[a-z_][a-z0-9_]*$"

# Functions / methods: snake_case, not length 1
function-rgx = "^(?!.$)[a-z_][a-z0-9_]*$"
method-rgx = "^(?!.$)[a-z_][a-z0-9_]*$"

# Classes: CapWords, not length 1
class-rgx = "^(?!.$)[A-Z_][a-zA-Z0-9_]*$"
typevar-rgx = "^[A-Za-z_][A-Za-z0-9_]*$"
good-names = ["_"]