✨ feat(repository): add Repository.open() unified entry point (#404)#407
Merged
Conversation
Design for unified entry point with namespace-first UX, auto-provision, fluent builder, and local endpoint special-casing cleanup. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace Repository.connect() with Repository.open() as the single recommended entry point. Namespace is now the primary positional arg, stack defaults via ZAEL_STACK env var or "zae-limiter", and namespace defaults via ZAEL_NAMESPACE env var or "default". Key changes: - Add Repository.open() with auto-provision (deploys stack if missing, registers namespace if not found) - Make RepositoryBuilder zero-arg with .stack(), .region(), .endpoint_url() fluent methods - Remove local endpoint special-casing in version check (runs everywhere) - Remove connect() (unreleased, no deprecation needed) - Add resolve_stack_name() and resolve_namespace_name() to naming.py Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ndException errors (#404) Cover the else branch in Repository.open() that re-raises ClientError when the error code is not ResourceNotFoundException. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
sodre
added
api-design
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #407 +/- ##
==========================================
+ Coverage 91.76% 91.80% +0.03%
==========================================
Files 33 33
Lines 7333 7367 +34
==========================================
+ Hits 6729 6763 +34
Misses 604 604
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
…ct()/builder(args) to open()/builder() (#404) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
…onstructor param (#404) SyncRepository.open() is generated from async Repository.open() and doesn't accept parallel_mode. Set it directly on the repo instance after construction. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…rator (#404) Update generate_sync.py to target open() instead of the removed connect() when injecting the sync-only parallel_mode parameter. Revert test workaround to use the proper keyword argument. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…)/builder() (#404) Update all documentation files and one missed e2e test to use the new Repository.open() and zero-arg builder() APIs. Fixes 21 doctest failures and the test_namespace_cli_lifecycle integration failure in CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…x LocalStack doc (#404) Add test verifying _check_and_update_version_auto runs when endpoint_url is set (no local endpoint skip). Update LocalStack docs to use Repository.open() instead of builder with enable_aggregator(False). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
⚠️ Performance Alert ⚠️
Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.40.
| Benchmark suite | Current: 90f5068 | Previous: 55bb4c0 | Ratio |
|---|---|---|---|
tests/benchmark/test_operations.py::TestOptimizationComparison::test_cascade_cache_enabled |
130.03580261305905 iter/sec (stddev: 0.023304082880899784) |
183.5925467475057 iter/sec (stddev: 0.00022160107543068607) |
1.41 |
This comment was automatically generated by workflow using github-action-benchmark.
…on (#404) Most doc examples were using Repository.open(stack="...", region="...") which gives the wrong impression that stack/region are required. Since open() defaults to sensible values (stack="zae-limiter", namespace="default"), examples should use the simpler form. Billing/api isolation examples now use namespaces instead of separate stacks, which better represents the intended usage pattern. Also patches SyncRepository in doctest fixtures so sync examples using the default stack name work against moto. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…#404) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…xamples (#404) Replace imperative open() + set_system_defaults() with declarative builder().namespace().on_unavailable().build() in the "Choose Based on Risk" section. Also register "billing" and "api" namespaces in doctest fixtures so builder examples can resolve them. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…oyment guide (#404) The deployment page is about infrastructure provisioning, so examples should use Repository.builder() rather than Repository.open(). Also mention both open() and builder().build() as auto-registering the default namespace. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…pace (#404) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…paces (#404) The note incorrectly stated that namespaces must be pre-registered for CLI data-access commands. Repository.open() auto-registers namespaces if they don't exist yet. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Repository.open()as the unified entry point with namespace-first UX and auto-provision (stack not found -> deploy with defaults, namespace not found -> register)Repository.builder()fully fluent with zero positional args, adding.stack(),.region(),.endpoint_url()chain methodsRepository.connect()(no deprecation needed since it was never released)resolve_stack_name()helper innaming.pyfor stack resolution from arg ->ZAEL_STACKenv var ->"zae-limiter"defaultopen()as the primary entry pointdocs/plans/2026-02-19-repository-open-design.mdTest plan
open()fast path (infra + namespace exist)open()auto-provision (infra missing)open()auto-register namespace (infra exists, namespace missing)open()re-raising non-ResourceNotFoundException errors.stack(),.region(),.endpoint_url()open()connect()tests migrated toopen()Closes #404
🤖 Generated with Claude Code