Skip to main content

pdum_gcp

CI PyPI Python 3.12+ License: MIT Code style: ruff

A GCP admin toolbox

Introduction

pdum_gcp is a toolbox for seasoned administrators who need to nurture Google Cloud estates that sprawl across multiple organizations. Think of the kind of tasks you might script in Terraform, except you want an interactive, incremental workflow that lets one trusted human explore, prototype, and tidy up quickly. This library intentionally does not scale beyond a tiny circle of grizzled operators—ideally a team of one—because it assumes every participating identity has god-like access across those organizations.

The focus here is admin hygiene: inspecting estates, checking IAM, enabling required APIs, and wiring up billing or quota projects. Once the scaffolding exists, you drop back into the regular Google Cloud Python clients to actually use the resources. A core tenet is “bring your own identity”: everything runs under your Application Default Credentials, which belong to you, not the orgs you help. That makes this powerful, but also dangerous—misplaced trust, compromised credentials, or sloppy copy/paste can translate into real financial and operational damage.

Use this library only if you:

  • Operate in small, high-trust environments where rapid create/tear-down cycles matter.
  • Regularly hop between organizations or short-lived projects.
  • Understand that you are working with loaded weapons and accept the risk.

Feature Highlights

  • Pre-flight your environment with doctor() to confirm identity, quota project, and API readiness.
  • Explore estates with list_organizations(), walk_projects(), and container helpers.
  • Resolve quota projects and billing details with quota_project() and billing sentinels.
  • Inspect IAM with get_iam_policy() and list_roles() before making changes.
  • Map friendly API names to service IDs via lookup_api() and the bundled catalog.

🧭 Ready to see it in action? Follow the Interactive Admin Tutorial for a guided, output-rich walkthrough (with sensitive identifiers anonymized).

Development

This project uses UV for dependency management.

Setup

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/habemus-papadum/pdum_gcp.git
cd pdum_gcp

# Provision the entire toolchain (uv sync, pnpm install, widget build, pre-commit hooks)
./scripts/setup.sh

Important for Development:

  • ./scripts/setup.sh is idempotent—rerun it after pulling dependency changes
  • Use uv sync --frozen to ensure the lockfile is respected when installing Python deps

Running Tests

# Run all tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_example.py

# Run a specific test function
uv run pytest tests/test_example.py::test_version

# Run tests with coverage
uv run pytest --cov=src/pdum/gcp --cov-report=xml --cov-report=term

Code Quality

# Check code with ruff
uv run ruff check .

# Format code with ruff
uv run ruff format .

# Fix auto-fixable issues
uv run ruff check --fix .

Building

# Sync the environment the way CI does
./scripts/build.sh

# Or build just the Python distribution artifacts
uv build

Releasing

Releases run from the release GitHub Actions workflow, which calls ship:

# Plan first (the default), then release for real
gh workflow run release.yml -f bump=minor -f dry_run=true
gh workflow run release.yml -f bump=minor -f dry_run=false

Each release is tagged habemus-papadum-gcp-v<version> on the commit it was built from. Between releases pyproject.toml carries <last release>+dev; ship sets the release version, builds, tests, publishes to PyPI, tags, and restores the development marker. To see the plan locally:

uv run ship release habemus-papadum-gcp --bump minor --dry-run

Install the pre-commit hooks with uv run pre-commit install (pre-commit is in the dev group); ./scripts/setup.sh does this.

Automation scripts

  • ./scripts/setup.sh – bootstrap uv and pre-commit hooks
  • ./scripts/build.sh – sync the environment the way CI does
  • ./scripts/test_notebooks.sh – execute demo notebooks (uses ./scripts/nb.sh under the hood)
  • ./scripts/setup-visual-tests.sh – install Playwright browsers for visual tests

License

MIT License - see LICENSE file for details.

Metadata

Release files for habemus-papadum-gcp 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for habemus-papadum-gcp 0.6.1
File Size Uploaded Provenance Actions
habemus_papadum_gcp-0.6.1.tar.gz 290.9 kB Without provenance Details for habemus_papadum_gcp-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for habemus-papadum-gcp 0.6.1
File Interpreter ABI Platform Actions
habemus_papadum_gcp-0.6.1-py3-none-any.whl Python 3 none any Details for habemus_papadum_gcp-0.6.1-py3-none-any.whl

Total release size: 331.1 kB

Release files / habemus_papadum_gcp-0.6.1.tar.gz

Download URL habemus_papadum_gcp-0.6.1.tar.gz
Size 290.9 kB
Tags Source
SHA-256 checksum
How to use checksums
6bcd470b5f767e76f3cd2a19972beb980895be377d1fa595ef2ca2ff0f8aeeb2
BLAKE2b-256 checksum
How to use checksums
e958e8ae902ec9435d8e7ea111e059f1b2c57ee72c3a2d324335a5e0b714256e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / habemus_papadum_gcp-0.6.1-py3-none-any.whl

Download URL habemus_papadum_gcp-0.6.1-py3-none-any.whl
Size 40.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d684ee56eaf94c10db099f62f5e57f0b0af67f2ea83eb764af5966d55b1589f2
BLAKE2b-256 checksum
How to use checksums
465a936326204c16e1ff2631315b9ecb895d1b57a3510ddec87a7c8217b6723d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for habemus-papadum-gcp 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page