From 6f83afe355a60bd9677536e1bb13b212dca5460a Mon Sep 17 00:00:00 2001 From: Tristen Harr Date: Fri, 30 Aug 2024 10:50:55 -0500 Subject: [PATCH] update docs --- CHANGELOG.md | 3 + README.md | 140 +++++++++++++++++----------------------- docs/code-of-conduct.md | 74 +++++++++++++++++++++ docs/contributing.md | 39 +++++++++++ docs/index.md | 9 +++ docs/logo.svg | 2 + docs/production.md | 48 ++++++++++++++ docs/security.md | 30 +++++++++ docs/support.md | 11 ++++ 9 files changed, 275 insertions(+), 81 deletions(-) create mode 100644 docs/code-of-conduct.md create mode 100644 docs/contributing.md create mode 100644 docs/index.md create mode 100644 docs/logo.svg create mode 100644 docs/production.md create mode 100644 docs/security.md create mode 100644 docs/support.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e9c642..cd931a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ This changelog documents the changes between release versions. ## [Unreleased] Changes to be included in the next upcoming release +## [0.1.0] - 2024-08-22 +* Update Documentation for ndc-hub + ## [0.0.45] - 2024-08-19 * Update SDK to fix input type casts diff --git a/README.md b/README.md index 68681cb..ed0093b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ -### Hasura Python Lambda Connector +# Hasura Python Lambda Connector + + +[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/connectors/python) +[![ndc-hub](https://img.shields.io/badge/ndc--hub-python-blue.svg?style=flat)](https://hasura.io/connectors/python) +[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](https://github.com/hasura/ndc-python-lambda/blob/main/LICENSE.txt) +[![Status](https://img.shields.io/badge/status-alpha-yellow.svg?style=flat)](https://github.com/hasura/ndc-python-lambda/blob/main/README.md) This connector allows you to write Python code and call it using Hasura! @@ -6,119 +12,91 @@ With Hasura, you can integrate -- and even host -- this business logic directly You can handle custom business logic using the Python Lambda data connector. Using this connector, you can transform or enrich data before it reaches your customers, or perform any other business logic you may need. -You can then integrate these functions as individual commands in your metadata and API. -This process enables you to simplify client applications and speed up your backend development! +You can then integrate these functions as individual commands in your metadata and API. This process enables you to simplify client applications and speed up your backend development! -## Setting up the Python Lambda connector +This connector is built using the [Python Data Connector SDK](https://github.com/hasura/ndc-sdk-python) and implements the [Data Connector Spec](https://github.com/hasura/ndc-spec). -### Prerequisites: -In order to follow along with this guide, you will need: -* [The DDN CLI, VS Code extension, and Docker installed](https://hasura.io/docs/3.0/getting-started/build/prerequisites/) -* Python version `>= 3.11` +## Before you get Started -In this guide we will setup a new Hasura DDN project from scratch. +1. The [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/) installed +2. A [supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph) +3. A [subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph) -### Step-by-step guide +The steps below explain how to Initialize and configure a connector for local development. You can learn how to deploy a connector — after it's been configured — [here](https://hasura.io/docs/3.0/getting-started/deployment/deploy-a-connector). -Create a new directory that will contain your Hasura project and change directories into it. +## Using the Python connector -```mkdir ddn && cd ddn``` +### Step 1: Authenticate your CLI session -Create a new supergraph: +```bash +ddn auth login +``` -```ddn supergraph init --dir .``` +### Step 2: Configure the connector -Start a watch session, additionally split of a new terminal to continue running commands from. +Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while providing a name for the connector in the prompt: -```HASURA_DDN_PAT=$(ddn auth print-pat) docker compose up --build --watch``` +```bash +ddn connector init python -i +``` -In the new terminal, perform a local build: +#### Step 2.1: Choose the `hasura/python` option from the list -```ddn supergraph build local --output-dir engine``` +#### Step 2.2: Choose a port for the connector -Initialize a subgraph: +The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the default suggested port. -``` -ddn subgraph init python \ - --dir python \ - --target-supergraph supergraph.local.yaml \ - --target-supergraph supergraph.cloud.yaml -``` +### Step 3: Introspect the connector -Initialize a Python connector: +Introspecting the connector will generate a `config.json` file and a `python.hml` file. -``` -ddn connector init python \ - --subgraph python/subgraph.yaml \ - --hub-connector hasura/python \ - --configure-port 8085 \ - --add-to-compose-file compose.yaml +```bash +ddn connector introspect python ``` -In the `.env.local` you will need to remove the `HASURA_CONNECTOR_PORT` variable which is set to `8085`. This is because the connector will run on that port but the docker-mapping is set to map 8085 -> 8080. +### Step 4: Add your resources -Before: -``` -OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317 -OTEL_SERVICE_NAME=python_python -HASURA_CONNECTOR_PORT=8085 -``` +You can add the models, commands, and relationships to your API by tracking them which generates the HML files. -After: -``` -OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317 -OTEL_SERVICE_NAME=python_python +```bash +ddn connector-link add-resources python ``` -Add the connector link: +### Step 5: Run your connector -``` -ddn connector-link add python \ - --subgraph python/subgraph.yaml \ - --configure-host http://local.hasura.dev:8085 \ - --target-env-file python/.env.python.local -``` +You can run your connector locally, or include it in the docker setup. -Stop the watch session using Ctrl-C and restart it. +#### Run the connector in Docker -``` -HASURA_DDN_PAT=$(ddn auth print-pat) docker compose up --build --watch +To include your connector in the docker setup, include its compose file at the top of your supergraph `compose.yaml` file like this: + +```yaml +include: + - path: app/connector/python/compose.yaml ``` -Once the connector is running, you can update the connector-link. +#### Run the connector locally -``` -ddn connector-link update python \ - --subgraph python/subgraph.yaml \ - --env-file python/.env.python.local \ - --add-all-resources -``` +To run your connector outside of Docker first go into the connector directory: -Push the build to the locally running engine: +`cd app/connector/python` -``` -ddn supergraph build local \ - --output-dir engine \ - --subgraph-env-file python:python/.env.python.local -``` +Install the requirements: -Now you should be able to write your code in the `functions.py` file, and each time you make changes and save the connector should automatically restart inside the watch session, you'll then need to track those changes and push them to engine. +`pip3 install -r requirements.txt` -You can do that by re-running the above commands: +Then run the connector locally: -To track the changes: +```ddn connector setenv --connector connector.yaml -- python3 functions.py serve``` -``` -ddn connector-link update python \ - --subgraph python/subgraph.yaml \ - --env-file python/.env.python.local \ - --add-all-resources -``` +## Documentation -To push these changes to engine: +View the full documentation for the Python Lambda connector [here](https://github.com/hasura/ndc-python-lambda/blob/main/docs/index.md). -``` -ddn supergraph build local \ - --output-dir engine \ - --subgraph-env-file python:python/.env.python.local -``` \ No newline at end of file +## Contributing + +Check out our [contributing guide](https://github.com/hasura/ndc-python-lambda/blob/main/docs/contributing.md) for more details. + +## License + +The Turso connector is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). \ No newline at end of file diff --git a/docs/code-of-conduct.md b/docs/code-of-conduct.md new file mode 100644 index 0000000..4d6ab54 --- /dev/null +++ b/docs/code-of-conduct.md @@ -0,0 +1,74 @@ +# Hasura Community Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming, inclusive and gender-neutral language (example: instead of "Hey guys", + you could use "Hey folks" or "Hey all") +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at community@hasura.io. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..3bc4568 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,39 @@ +# Contributing + +_First_: if you feel insecure about how to start contributing, feel free to ask us on our +[Discord channel](https://discordapp.com/invite/hasura) in the #contrib channel. You can also just go ahead with your contribution and we'll give you feedback. Don't worry - the worst that can happen is that you'll be politely asked to change something. We appreciate any contributions, and we don't want a wall of rules to stand in the way of that. + +However, for those individuals who want a bit more guidance on the best way to contribute to the project, read on. This document will cover what we're looking for. By addressing the points below, the chances that we can quickly merge or address your contributions will increase. + +## 1. Code of conduct + +Please follow our [Code of conduct](./code-of-conduct.md) in the context of any contributions made to Hasura. + +## 2. CLA + +For all contributions, a CLA (Contributor License Agreement) needs to be signed +[here](https://cla-assistant.io/hasura/ndc-python-lambda) before (or after) the pull request has been submitted. A bot will prompt contributors to sign the CLA via a pull request comment, if necessary. + +## 3. Ways of contributing + +### Reporting an Issue + +- Make sure you test against the latest released cloud version. It is possible that we may have already fixed the bug you're experiencing. +- Provide steps to reproduce the issue, including Database (e.g. Postgres) version and Hasura DDN version. +- Please include logs, if relevant. +- Create a [issue](https://github.com/hasura/ndc-python-lambda/issues/new/choose). + +### Working on an issue + +- We use the [fork-and-branch git workflow](https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/). +- Please make sure there is an issue associated with the work that you're doing. +- If you're working on an issue, please comment that you are doing so to prevent duplicate work by others also. +- Squash your commits and refer to the issue using `fix #` or `close #` in the commit message, at the end. For example: `resolve answers to everything (fix #42)` or `resolve answers to everything, fix #42` +- Rebase master with your branch before submitting a pull request. + +## 6. Commit messages + +- The first line should be a summary of the changes, not exceeding 50 characters, followed by an optional body which has more details about the changes. Refer to [this link](https://github.com/erlang/otp/wiki/writing-good-commit-messages) for more information on writing good commit messages. +- Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes". +- Don't capitalize the first letter of the summary line. +- Don't add a period/dot (.) at the end of the summary line. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..28fa11a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,9 @@ +# Python Lambda Documentation + +The Python Lambda connector is a [Hasura](https://hasura.io/) Native Data Connector. + +- [Code of Conduct](./code-of-conduct.md) +- [Contributing](./contributing.md) +- [Production](./production.md) +- [Support](./support.md) +- [Security](./security.md) \ No newline at end of file diff --git a/docs/logo.svg b/docs/logo.svg new file mode 100644 index 0000000..e771ee2 --- /dev/null +++ b/docs/logo.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/production.md b/docs/production.md new file mode 100644 index 0000000..8dfbf41 --- /dev/null +++ b/docs/production.md @@ -0,0 +1,48 @@ +# Hasura Python Lambda Connector in Production +We ship the Python connectors as Docker images. + +You can look at the Dockerfile in the root of the repository to see how the image is built. + +The connector can be run via a docker-compose file: + +``` +services: + app_python: + build: + context: . + dockerfile: .hasura-connector/Dockerfile + develop: + watch: + - path: requirements.txt + action: rebuild + target: /functions/requirements.txt + - path: ./ + action: sync+restart + target: /functions + environment: + HASURA_SERVICE_TOKEN_SECRET: $APP_PYTHON_HASURA_SERVICE_TOKEN_SECRET + OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: $APP_PYTHON_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT + OTEL_SERVICE_NAME: $APP_PYTHON_OTEL_SERVICE_NAME + extra_hosts: + - local.hasura.dev=host-gateway + ports: + - mode: ingress + target: 8080 + published: "8265" + protocol: tcp +``` + +The Dockerfile for this connector looks like: + +``` +FROM ghcr.io/hasura/ndc-python-lambda:v0.0.41 + +COPY requirements.txt /functions/ + +WORKDIR /functions +RUN python3 -m venv venv && \ + . venv/bin/activate && \ + pip install -r requirements.txt + +COPY ./ /functions +``` \ No newline at end of file diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..e6d4dd9 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,30 @@ +## Reporting Vulnerabilities + +We’re extremely grateful for security researchers and users that report vulnerabilities to the Hasura Community. All reports are thoroughly investigated by a set of community volunteers and the Hasura team. + +To report a security issue, please email us at [security@hasura.io](mailto:security@hasura.io) with all the details, attaching all necessary information. + +### When Should I Report a Vulnerability? + +- You think you have discovered a potential security vulnerability in the Hasura GraphQL Engine or related components. +- You are unsure how a vulnerability affects the Hasura GraphQL Engine. +- You think you discovered a vulnerability in another project that Hasura GraphQL Engine depends on (e.g. Heroku, Docker, etc). +- You want to report any other security risk that could potentially harm Hasura GraphQL Engine users. + +### When Should I NOT Report a Vulnerability? + +- You need help tuning Hasura GraphQL Engine components for security. +- You need help applying security related updates. +- Your issue is not security related. + +## Security Vulnerability Response + +Each report is acknowledged and analyzed by the project's maintainers and the security team within 3 working days. + +The reporter will be kept updated at every stage of the issue's analysis and resolution (triage -> fix -> release). + +## Public Disclosure Timing + +A public disclosure date is negotiated by the Hasura product security team and the bug submitter. We prefer to fully disclose the bug as soon as possible once a user mitigation is available. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to a few weeks. We expect the time-frame between a report to a public disclosure to typically be in the order of 7 days. The Hasura GraphQL Engine maintainers and the security team will take the final call on setting a disclosure date. + +(Some sections have been inspired and adapted from [https://github.com/kubernetes/website/blob/master/content/en/docs/reference/issues-security/security.md](https://github.com/kubernetes/website/blob/master/content/en/docs/reference/issues-security/security.md)). \ No newline at end of file diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 0000000..a77ff1f --- /dev/null +++ b/docs/support.md @@ -0,0 +1,11 @@ +# Support & Troubleshooting + +The documentation and community will help you troubleshoot most issues. If you have encountered a bug or need to get in touch with us, you can contact us using one of the following channels: +* Support & feedback: [Discord](https://discord.gg/hasura) +* Issue & bug tracking: [GitHub issues](https://github.com/hasura/ndc-python-lambda/issues) +* Follow product updates: [@HasuraHQ](https://twitter.com/hasurahq) +* Talk to us on our [website chat](https://hasura.io) + +We are committed to fostering an open and welcoming environment in the community. Please see the [Code of Conduct](code-of-conduct.md). + +If you want to report a security issue, please [read this](security.md). \ No newline at end of file