feat: Introduce Environment constants for Sandbox and Production

[Dannyorji]

Description

This PR introduces a formalized Environment enum in the SDK to handle the resolution of Horizon URLs, network passphrases, and Shade backend base URLs. This ensures that the HTTP client and Stellar layer can automatically resolve the correct settings for staging and live environments without requiring manual user mapping.

Changes

• Environment Enum: Replaced the legacy MAINNET and TESTNET constants with SANDBOX and PRODUCTION in shade/config.py.
• URL & Passphrase Resolution: Mapped the respective environments to their correct Horizon URL, network passphrase, and Shade backend base URL.
• Global & Client-level Configuration: Defaulted the SDK to SANDBOX to prevent accidental production interactions. Exposed shade.environment in shade/__init__.py to allow developers to set the environment globally.
• Environment Coercion: Implemented parse_environment() to allow users to set the environment using string shorthands like "sandbox" and "production". Invalid strings raise a ValueError.
• Test Updates: Updated existing unit tests to reflect these changes and added new tests to cover module-level environment overrides and invalid string inputs.

Acceptance Criteria Met

• shade.environment = "production" resolves to the mainnet Horizon URL and production API base.
• shade.environment = "sandbox" resolves to the testnet Horizon URL and staging API base.
• Invalid strings raise ValueError with the list of valid options.
• The SDK defaults to SANDBOX to protect developers.
• The Stellar layer reads Environment without separate configuration.

Closes #3

Summary by CodeRabbit

• New Features

  • Added a public environment setting that can be read and updated at the module level.
  • Gateway now accepts either an environment name or environment value, making configuration easier.
  • Added support for sandbox and production environment endpoints, including Horizon URLs.

• Bug Fixes

  • Improved default environment handling so new clients use the updated default automatically.
  • Validates environment values and rejects invalid inputs with a clear error.

[coderabbitai]

📝 Walkthrough

Walkthrough

Renames Environment enum members from MAINNET/TESTNET to PRODUCTION/SANDBOX, adds horizon_url property and parse_environment string coercion, sets the module default to SANDBOX, exposes shade.environment as a settable module-level property, updates Gateway to accept str | Environment | None with module-level fallback, and updates all tests accordingly.

Changes

Environment Refactor and Module-Level Property

Layer / File(s)	Summary
Environment enum, horizon_url, and parse_environment src/shade/config.py	Environment members renamed to SANDBOX/PRODUCTION with updated base_url and network_passphrase mappings. New horizon_url property added. parse_environment helper added for case-insensitive string coercion with ValueError on invalid input. Module-level environment defaulted to Environment.SANDBOX.
shade.environment module-level property src/shade/__init__.py	"environment" added to __all__. _ShadeModule gains an environment property: getter returns config.environment, setter calls config.parse_environment for string inputs before storing.
Gateway environment parameter and resolution src/shade/gateway.py	environment parameter changed to Optional[Environment | str] = None. Initialization resolves via parse_environment when provided, otherwise falls back to _config.environment. Default URL uses self.environment.base_url.
Test suite updates tests/test_api_base.py	Tests updated to PRODUCTION/SANDBOX, asserting SANDBOX default, module-level assignment, ValueError on invalid strings, Gateway environment fallback and per-client override, and updated horizon_url/network_passphrase/base_url enum assertions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ShadeProtocol/shade-python#29: Modifies the same Environment model in config.py, gateway.py environment handling, and the _ShadeModule property pattern in __init__.py.

Suggested reviewers

• codebestia

Poem

🐇 Hop, hop, the sandbox is safe,
No mainnet surprises to chafe!
PRODUCTION awaits when you're ready to go,
Just set shade.environment — it's not just for show.
A ValueError guards the gate with care,
The rabbit ships clean configs everywhere! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly reflects the main change: introducing Environment constants for sandbox and production.
Description check	✅ Passed	The description covers the change, issue, context, and acceptance criteria, though it omits the template's type, testing, and checklist sections.
Linked Issues check	✅ Passed	The code changes implement the requested Environment enum, coercion, defaults, and environment-based URL and passphrase resolution.
Out of Scope Changes check	✅ Passed	The changed files stay focused on environment handling and related tests, with no obvious unrelated or extraneous scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_api_base.py (1)

81-83: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Escape the regex in pytest.raises(match=...).

match= is a regex, so the . in "Invalid environment. ..." currently matches any character. Escaping the pattern (or using re.escape) makes the assertion exact and fixes the Ruff warning.

Proposed fix

-        with pytest.raises(ValueError, match="Invalid environment. Valid options are: 'sandbox', 'production'"):
+        with pytest.raises(
+            ValueError,
+            match=r"Invalid environment\. Valid options are: 'sandbox', 'production'",
+        ):
             shade.environment = "invalid"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_api_base.py` around lines 81 - 83, The pytest.raises match in
test_invalid_assignment_raises_value_error uses a regex pattern, so the
unescaped punctuation in the expected error string can match too broadly. Update
the assertion in test_invalid_assignment_raises_value_error to escape the full
message (for example via re.escape) so the ValueError check is exact and aligns
with the Ruff warning.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/test_api_base.py`:
- Around line 81-83: The pytest.raises match in
test_invalid_assignment_raises_value_error uses a regex pattern, so the
unescaped punctuation in the expected error string can match too broadly. Update
the assertion in test_invalid_assignment_raises_value_error to escape the full
message (for example via re.escape) so the ValueError check is exact and aligns
with the Ruff warning.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 97bf6fa1-36e0-45c4-992b-5d48005a37ad

📥 Commits

Reviewing files that changed from the base of the PR and between 5634c68 and 734b5de.

📒 Files selected for processing (4)

• src/shade/__init__.py
• src/shade/config.py
• src/shade/gateway.py
• tests/test_api_base.py

[codebestia]

LGTM!
Thank you for your contribution.