standardize logging behavior default to log level warn

[cbrady]

Summary

Standardizes how the Python SDK handles logging. The previous default logger emitted at DEBUG, flooding production consumers with diagnostics they did not opt into. This PR establishes a clean default and adds a configuration option for consumers who want more or less detail.

Behavior changes

Important

Default log level is now WARNING (previously DEBUG). If your application relied on the SDK's default logger emitting INFO or DEBUG lines, you'll see fewer log messages after upgrading. Re-enable verbose output with log_level=logging.DEBUG on SchematicConfig / AsyncSchematicConfig (see below).

Three rules now hold for SDK logging:

1. Default log level is WARNING. debug and info calls from the SDK are suppressed unless the consumer opts in.

2. The default logger's level is configurable via a new top-level config option log_level (accepts a logging level constant or its string name, e.g. "DEBUG"):

   from schematic.client import Schematic, SchematicConfig
   import logging
   
   client = Schematic("sch_...", config=SchematicConfig(log_level=logging.DEBUG))

3. A consumer-provided logger is used as-is. If you pass your own logging.Logger via the logger config option, the SDK does not override its level or attach handlers to it. Your logger's existing configuration is the source of truth; log_level is ignored in that case.

   import logging
   my_logger = logging.getLogger("my_app.schematic")
   my_logger.setLevel(logging.INFO)
   client = Schematic("sch_...", config=SchematicConfig(logger=my_logger))

Implementation notes

• DEFAULT_LOG_LEVEL and LogLevel are exported from schematic.logging for consumers who want the type alias.
• The default logger's StreamHandler is now tagged with the name schematichq-default. Repeated calls to get_default_logger find and update that handler's level rather than mutating any other handlers a consumer may have attached to a same-named logger out-of-band. No duplicate handlers ever stack.
• Both Schematic (sync) and AsyncSchematic (async) clients accept the new log_level option.

Test plan

• tests/custom/test_logging.py — 16 new tests covering: default WARNING, level configurability (int + string forms), handler-level sync, sync/async client wiring, custom-logger-wins behavior, foreign-handler isolation, no duplicate-handler stacking on repeat calls
• poetry run pytest -n auto — 294 tests pass
• poetry run mypy src — clean
• poetry run ruff check src/schematic/client.py src/schematic/logging.py tests/custom/test_logging.py — clean (also fixed pre-existing I001 on client.py while we were here)

Related

• Linear: SCHY-375
• Spec doc updated separately in schematic-api with the canonical logging contract and a cross-SDK conformance table (other SDKs to follow this pattern).

[bpapillon]

We should consider changing the PR title and/or commit message to note the change in default log level, so that it shows up in the release notes