| Name | gcp-pilot JSON |
| Version |
1.31.0
JSON |
| download |
| home_page | None |
| Summary | Google Cloud Platform Friendly Pilot |
| upload_time | 2024-12-09 18:46:53 |
| maintainer | Rodolfo Stangherlin, Diego Freire, Guilherme Araujo, Lucas Gomide |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
datastore orm
gcp
google cloud python
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://coveralls.io/github/flamingo-run/gcp-pilot)
[]() []() []()
# Google Cloud Pilot
## Installation
`pip install gcp-pilot`
Some APIs need extra packages, thus you must use `extras` to add them:
- Cloud Tasks: `pip install gcp-pilot[tasks]`
- Cloud Build: `pip install gcp-pilot[build]`
- Cloud Storage: `pip install gcp-pilot[storage]`
- Big Query: `pip install gcp-pilot[bigquery]`
- Speech: `pip install gcp-pilot[speech]`
- Sheets: `pip install gcp-pilot[sheets]`
- Pub/Sub: `pip install gcp-pilot[pubsub]`
- Datastore: `pip install gcp-pilot[datastore]`
- Cloud DNS: `pip install gcp-pilot[dns]`
- Secret Manager: `pip install gcp-pilot[secret]`
- Healthcare Engine: `pip install gcp-pilot[healthcare]`
- IAM: `pip install gcp-pilot[iam]`
## Usage
```
from gcp_pilot.resource import ResourceManager
grm = ResourceManager()
```
## Default Values
### Credentials
`gcp-pilot` uses [ADC](https://cloud.google.com/docs/authentication/production#automatically) to detect credentials. This means that you must have one of the following setups:
- Environment variable `GOOGLE_APPLICATION_CREDENTIALS` pointing to the JSON file with the credentials
- Run inside GCP (Compute Engine, Cloud Run, GKE, AppEngine), so the machine's credentials will be used
- Run locally after authenticating with `gcloud auth application-default login`
You can also globally set a service account using the environment variable `DEFAULT_SERVICE_ACCOUNT`, which will require impersonation.
### Project
When creating a client, a default project is defined by using the project that the credentials belongs to.
Clients that support managing resources from other projects can be overwritten per call.
> Example: you create a `BigQuery` client using credentials from `project_a`.
All calls will query datasets from `project_a`, unless another project is passed as parameter when performing the call.
You can also globally set a project using the environment variable `DEFAULT_PROJECT`
### Location
Very similar to default project, a default location is defined by using the project's location.
The project's location will exist if you ever enabled AppEngine, so you had to set a location then.
Otherwise, no default location will be set.
You can also globally set a location using the environment variable `DEFAULT_LOCATION` and reduce the amount of API calls
when creating clients.
## Why Use ``gcp-pilot``
_"Since Google already has a [generic API client](https://github.com/googleapis/google-api-python-client) and so many [specific clients](https://github.com/googleapis?q=python&type=&language=), why should I use this library?"_
Google's has 2 types of clients:
- **dedicated**: custom-made for the APIs. They are excellent: they implement high level interaction with the API with friendly methods. The `gcp-pilot` can adds its value by handling authentication, friendly errors and parameter fallback.
- **generic**: a single client that is capable of dynamically calling any REST API. They are a pain to use: very specific calls that must be translated from the documentation. The `gcp-pilot` comes in handy to add high-level interaction with friendly method such as `Calendar.create_event`, on top of all other vantages cited above.
### Parameter Fallback
Most API endpoints require `project_id` (sometimes even `project_number`) and `location`.
So `gcp-pilot` automatically detects these values for you, based on your credentials (although it'll require extra permissions and API calls).
If you use multiple projects, and your credentials is accessing other projects, you can still customize the parameters on each call to avoid the default fallback.
### Friendly Errors
Most APIs return a generic ``HttpException`` with am embedded payload with error output, and also there's a couple of different structures for these payloads.
So `gcp-pilot` tries its best to convert these exceptions into more friendly ones, such as `NotFound`, `AlreadyExists` and `NotAllowed`.
It'll be much easier to capture these exceptions and handle them by its type.
### Identification Features
- **Authentication**: each client uses [ADC](https://cloud.google.com/docs/authentication/production#automatically),
which consists on trying to detect the service account with fallbacks: SDK > Environment Variable > Metadata
- **Impersonation**: it's possible to create clients with ``impersonate_account`` parameter that [impersonates](https://cloud.google.com/iam/docs/impersonating-service-accounts#allow-impersonation) another account.
- **Delegation**: services _(eg. Google Workspace)_ that requires specific subjects are automatically delegated, sometimes even performing additional credential signatures.
- **Region**: most GCP services requires a location to work on *(some even require specific locations)*. If not provided, the clients use the project's default location, as defined by App Engine.
- **Authorization**: OIDC authorization is automatically generated for services *(eg. CloudRun)* that require authentication to be used.
### Auto-Authorization
Some services require specific authorizations that should be setup prior to its usage, some examples:
- [Pub/Sub] subscribe to a topic with authenticated push;
- [Cloud Scheduler] schedule a job to trigger a Cloud Run service;
- [Cloud Tasks] queue a task to trigger a Cloud Run service;
In these cases, `gcp-pilot` tries its best to assure that the required permissions are properly set up
before the actual request is made.
### Integration
Some services can be integrated, and `gcp-pilot` does just that in a seamless way by adding helper methods.
Example: you can subscribe to Google Cloud Build's events to be notified by every build step.
By using `CloudBuild.subscribe`, the `gcp-pilot` creates a subscription (and the topic, if needed) in the Google Pub/Sub service.
## Supported APIs
- IAM
- manage service accounts
- manage permissions
- encode & decode JWT tokens
- Identity Platform
- sign in users
- sign up users
- reset password flow
- verify email flow
- generate authentication magic links (OOB tokens)
- manage authorized domains
- Credentials
- manage API Keys
- Resource Manager
- manage projects
- manage permissions
- Secret Manager
- manage secrets
- Identity Aware Proxy
- generate OIDC token
- Source Repositories
- manage repositories
- Directory:
- manage users
- manage groups
- People:
- get people
- Cloud SQL
- manage instances
- manage databases
- manage users
- Cloud Storage
- manage buckets
- manage files
- Cloud Build
- manage triggers
- Cloud Functions
- manager functions
- manage permissions
- Cloud Scheduler
- manage schedules
- Cloud Tasks
- manage tasks & queues
- Cloud Run
- read services
- manage domain mappings [[1]](https://cloud.google.com/run/docs/mapping-custom-domains#adding_verified_domain_owners_to_other_users_or_service_accounts)
- API Gateway
- manage APIs
- manage API Configs
- manage Gateways
- Service Usage
- enable/disable APIs and Services
- BigQuery
- manage datasets
- perform queries
- Calendar
- manage events
- Google Chats
- build complex messages
- call webhook
- interact as bot
- Cloud Directory
- manage groups
- Cloud DNS
- manage DNS zones
- manage zone's registers
- Sheets
- manage spreadsheets (powered by gspread)
- Speech
- recognize speech from audio
- Datastore
- Object Mapping ("ORM-ish" management of documents)
- Monitoring
- reporting errors
- logging
- manage custom services
- Healthcare
- Manage datasets
- Manage stores
- Manage FHIR resources: _powered by [fhir-resources](https://github.com/nazrulworld/fhir.resources)_
- Datastream
- Read/Delete streams
- Read Stream's Objects
- Start/Stop object backfill
Raw data
{
"_id": null,
"home_page": null,
"name": "gcp-pilot",
"maintainer": "Rodolfo Stangherlin, Diego Freire, Guilherme Araujo, Lucas Gomide",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "datastore orm, gcp, google cloud python",
"author": null,
"author_email": "Joao Daher <joao@daher.dev>",
"download_url": "https://files.pythonhosted.org/packages/01/b0/256d623b5a92027f70ba9a656d079bc1e9cedd91ac707daaa627631d7edd/gcp_pilot-1.31.0.tar.gz",
"platform": null,
"description": "\n[](https://coveralls.io/github/flamingo-run/gcp-pilot)\n[]() []() []()\n\n# Google Cloud Pilot\n\n## Installation\n\n`pip install gcp-pilot`\n\nSome APIs need extra packages, thus you must use `extras` to add them:\n\n- Cloud Tasks: `pip install gcp-pilot[tasks]`\n- Cloud Build: `pip install gcp-pilot[build]`\n- Cloud Storage: `pip install gcp-pilot[storage]`\n- Big Query: `pip install gcp-pilot[bigquery]`\n- Speech: `pip install gcp-pilot[speech]`\n- Sheets: `pip install gcp-pilot[sheets]`\n- Pub/Sub: `pip install gcp-pilot[pubsub]`\n- Datastore: `pip install gcp-pilot[datastore]`\n- Cloud DNS: `pip install gcp-pilot[dns]`\n- Secret Manager: `pip install gcp-pilot[secret]`\n- Healthcare Engine: `pip install gcp-pilot[healthcare]`\n- IAM: `pip install gcp-pilot[iam]`\n\n\n## Usage\n\n```\nfrom gcp_pilot.resource import ResourceManager\n\ngrm = ResourceManager()\n```\n\n## Default Values\n\n### Credentials\n\n`gcp-pilot` uses [ADC](https://cloud.google.com/docs/authentication/production#automatically) to detect credentials. This means that you must have one of the following setups:\n- Environment variable `GOOGLE_APPLICATION_CREDENTIALS` pointing to the JSON file with the credentials\n- Run inside GCP (Compute Engine, Cloud Run, GKE, AppEngine), so the machine's credentials will be used\n- Run locally after authenticating with `gcloud auth application-default login`\n\nYou can also globally set a service account using the environment variable `DEFAULT_SERVICE_ACCOUNT`, which will require impersonation.\n\n### Project\n\nWhen creating a client, a default project is defined by using the project that the credentials belongs to.\n\nClients that support managing resources from other projects can be overwritten per call.\n\n> Example: you create a `BigQuery` client using credentials from `project_a`.\nAll calls will query datasets from `project_a`, unless another project is passed as parameter when performing the call.\n\nYou can also globally set a project using the environment variable `DEFAULT_PROJECT`\n\n### Location\n\nVery similar to default project, a default location is defined by using the project's location.\nThe project's location will exist if you ever enabled AppEngine, so you had to set a location then.\nOtherwise, no default location will be set.\n\nYou can also globally set a location using the environment variable `DEFAULT_LOCATION` and reduce the amount of API calls \nwhen creating clients.\n\n## Why Use ``gcp-pilot``\n\n_\"Since Google already has a [generic API client](https://github.com/googleapis/google-api-python-client) and so many [specific clients](https://github.com/googleapis?q=python&type=&language=), why should I use this library?\"_\n\nGoogle's has 2 types of clients:\n- **dedicated**: custom-made for the APIs. They are excellent: they implement high level interaction with the API with friendly methods. The `gcp-pilot` can adds its value by handling authentication, friendly errors and parameter fallback.\n- **generic**: a single client that is capable of dynamically calling any REST API. They are a pain to use: very specific calls that must be translated from the documentation. The `gcp-pilot` comes in handy to add high-level interaction with friendly method such as `Calendar.create_event`, on top of all other vantages cited above.\n\n### Parameter Fallback\n\nMost API endpoints require `project_id` (sometimes even `project_number`) and `location`.\n\nSo `gcp-pilot` automatically detects these values for you, based on your credentials (although it'll require extra permissions and API calls).\n\nIf you use multiple projects, and your credentials is accessing other projects, you can still customize the parameters on each call to avoid the default fallback.\n\n\n### Friendly Errors\n\nMost APIs return a generic ``HttpException`` with am embedded payload with error output, and also there's a couple of different structures for these payloads.\n\nSo `gcp-pilot` tries its best to convert these exceptions into more friendly ones, such as `NotFound`, `AlreadyExists` and `NotAllowed`.\n\nIt'll be much easier to capture these exceptions and handle them by its type.\n\n\n### Identification Features\n\n- **Authentication**: each client uses [ADC](https://cloud.google.com/docs/authentication/production#automatically),\nwhich consists on trying to detect the service account with fallbacks: SDK > Environment Variable > Metadata\n- **Impersonation**: it's possible to create clients with ``impersonate_account`` parameter that [impersonates](https://cloud.google.com/iam/docs/impersonating-service-accounts#allow-impersonation) another account.\n- **Delegation**: services _(eg. Google Workspace)_ that requires specific subjects are automatically delegated, sometimes even performing additional credential signatures.\n- **Region**: most GCP services requires a location to work on *(some even require specific locations)*. If not provided, the clients use the project's default location, as defined by App Engine.\n- **Authorization**: OIDC authorization is automatically generated for services *(eg. CloudRun)* that require authentication to be used.\n\n### Auto-Authorization\n\nSome services require specific authorizations that should be setup prior to its usage, some examples:\n- [Pub/Sub] subscribe to a topic with authenticated push;\n- [Cloud Scheduler] schedule a job to trigger a Cloud Run service;\n- [Cloud Tasks] queue a task to trigger a Cloud Run service;\n\nIn these cases, `gcp-pilot` tries its best to assure that the required permissions are properly set up\nbefore the actual request is made.\n\n### Integration\n\nSome services can be integrated, and `gcp-pilot` does just that in a seamless way by adding helper methods.\n\nExample: you can subscribe to Google Cloud Build's events to be notified by every build step.\n\nBy using `CloudBuild.subscribe`, the `gcp-pilot` creates a subscription (and the topic, if needed) in the Google Pub/Sub service.\n\n## Supported APIs\n\n- IAM\n - manage service accounts\n - manage permissions\n - encode & decode JWT tokens\n- Identity Platform\n - sign in users\n - sign up users\n - reset password flow\n - verify email flow\n - generate authentication magic links (OOB tokens)\n - manage authorized domains\n- Credentials\n - manage API Keys\n- Resource Manager\n - manage projects\n - manage permissions\n- Secret Manager\n - manage secrets\n- Identity Aware Proxy\n - generate OIDC token\n- Source Repositories\n - manage repositories\n- Directory:\n - manage users\n - manage groups\n- People:\n - get people\n- Cloud SQL\n - manage instances\n - manage databases\n - manage users\n- Cloud Storage\n - manage buckets\n - manage files\n- Cloud Build\n - manage triggers\n- Cloud Functions\n - manager functions\n - manage permissions\n- Cloud Scheduler\n - manage schedules\n- Cloud Tasks\n - manage tasks & queues\n- Cloud Run\n - read services\n - manage domain mappings [[1]](https://cloud.google.com/run/docs/mapping-custom-domains#adding_verified_domain_owners_to_other_users_or_service_accounts)\n- API Gateway\n - manage APIs\n - manage API Configs\n - manage Gateways\n- Service Usage\n - enable/disable APIs and Services\n- BigQuery\n - manage datasets\n - perform queries\n- Calendar\n - manage events\n- Google Chats\n - build complex messages\n - call webhook\n - interact as bot\n- Cloud Directory\n - manage groups\n- Cloud DNS\n - manage DNS zones\n - manage zone's registers\n- Sheets\n - manage spreadsheets (powered by gspread)\n- Speech\n - recognize speech from audio\n- Datastore\n - Object Mapping (\"ORM-ish\" management of documents)\n- Monitoring\n - reporting errors\n - logging\n - manage custom services\n- Healthcare\n - Manage datasets\n - Manage stores\n - Manage FHIR resources: _powered by [fhir-resources](https://github.com/nazrulworld/fhir.resources)_\n- Datastream\n - Read/Delete streams\n - Read Stream's Objects\n - Start/Stop object backfill",
"bugtrack_url": null,
"license": null,
"summary": "Google Cloud Platform Friendly Pilot",
"version": "1.31.0",
"project_urls": null,
"split_keywords": [
"datastore orm",
" gcp",
" google cloud python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c4c69e24d403a8726fbd1b510b33e25400705947d1d285e39454304a69504153",
"md5": "f55dc5e7f9acd969fcaa7f2d84bd45ed",
"sha256": "57e086ee12e0823103f9c3a93891e31eea6b15c745cba05702606dca631f6ab5"
},
"downloads": -1,
"filename": "gcp_pilot-1.31.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f55dc5e7f9acd969fcaa7f2d84bd45ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 72517,
"upload_time": "2024-12-09T18:46:51",
"upload_time_iso_8601": "2024-12-09T18:46:51.785079Z",
"url": "https://files.pythonhosted.org/packages/c4/c6/9e24d403a8726fbd1b510b33e25400705947d1d285e39454304a69504153/gcp_pilot-1.31.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01b0256d623b5a92027f70ba9a656d079bc1e9cedd91ac707daaa627631d7edd",
"md5": "ca63c572d558578d71888e4b45ce8157",
"sha256": "ccd182ebb9fb753220a8685dd971c097cbbe8dd08838190b734aeff3fc45e5ba"
},
"downloads": -1,
"filename": "gcp_pilot-1.31.0.tar.gz",
"has_sig": false,
"md5_digest": "ca63c572d558578d71888e4b45ce8157",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 105760,
"upload_time": "2024-12-09T18:46:53",
"upload_time_iso_8601": "2024-12-09T18:46:53.779918Z",
"url": "https://files.pythonhosted.org/packages/01/b0/256d623b5a92027f70ba9a656d079bc1e9cedd91ac707daaa627631d7edd/gcp_pilot-1.31.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 18:46:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gcp-pilot"
}
