update docs

Author: Tristen Harr

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
 

README.md

@@ -1,124 +1,102 @@
-### Hasura Python Lambda Connector
+# Hasura Python Lambda Connector
+<a href="https://www.python.org/"><img src="https://github.com/hasura/ndc-python-lambda/blob/main/docs/logo.svg" align="right" width="200"></a>
+
+[![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!
 
 With Hasura, you can integrate -- and even host -- this business logic directly with Hasura DDN and your API.
 
 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
-```
+## 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).

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 [email protected]. 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

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 #<issue-no>` or `close #<issue-no>` 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.

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)

docs/logo.svg

@@ -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
+```