diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 161a3e45..49da1c0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -All instructions for contributing can be found here: https://www.buildflow.dev/docs/developers/contribute +All instructions for contributing can be found here: https://docs.launchflow.com/buildflow/developers/contribute diff --git a/README.md b/README.md index 42dc9b87..359547ea 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ -# ⚒️ BuildFlow +
+ +![BuildFlow Logo](docs/images/buildflow.png) + +
+ +### **⚒️ Build your entire system in minutes using pure Python. ⚒️** ![CI](https://github.com/launchflow/buildflow/actions/workflows/python_ci.yaml/badge.svg) ![Release Tests](https://github.com/launchflow/buildflow/actions/workflows/release_tests.yaml/badge.svg) @@ -6,17 +12,95 @@ [![codecov](https://codecov.io/gh/launchflow/buildflow/branch/main/graph/badge.svg?token=AO0TP8XG7X)](https://codecov.io/gh/launchflow/buildflow) [![Slack Icon](https://img.shields.io/badge/slack-@launchflowusers-brightgreen.svg?logo=slack)](https://join.slack.com/t/launchflowusers/shared_invite/zt-27wlowsza-Uiu~8hlCGkvPINjmMiaaMQ) -## Overview +
+ +## 🤔 What is BuildFlow? + +**BuildFlow** is a Python framework that allows you to build your entire backend system using one framework. With our simple decorator pattern you can turn any function into a component of your backend system. Allowing you to **serve data over HTTP, dump data to a datastore, or process async data from message queues**. All of these can use our built in IO connectors allowing you to create, manage, and connect to your cloud resources using pure Python. + +### Key Features + +#### Common Serving & Processing Patterns | 📖 [Docs](https://docs.launchflow.com/buildflow/introduction) + +Turn any function into a component of your backend system. + +```python +# Serve traffic over HTTP or Websockets +service = app.service("my-service") +@service.endpoint("/", method="GET") +def get(): + return "Hello World" + +# Collect, transform, and write data to storage +@app.collector("/collect", method="POST", sink=SnowflakeTable(...)) +def collect(request: Dict[str, Any]): + return element + +# Process data from message queues such as Pub/Sub & SQS +@app.consumer(source=SQSQueue(...), sink=BigQuery(...)) +def process(element: Dict[str, Any]): + return element +``` + +#### Infrastructure from Code | 📖 [Docs](https://docs.launchflow.com/buildflow/introduction) + +Create and connect to cloud resources using python (powered by [Pulumi](https://github.com/pulumi/pulumi)) + +```python +# Use Python objects to define your infrastructure +sqs_queue = SQSQueue("queue-name") +gcs_bucket = GCSBucket("bucket-name") -**BuildFlow**, is an open source framework for building large scale systems using Python. All you need to do is describe where your input is coming from and where your output should be written, and BuildFlow handles the rest. **No configuration outside of the code is required**. +# Your application manages its own infrastructure state +app.manage(s3_bucket, gcs_bucket) -Key Features (all provided out-of-the-box): +# Use the same resource objects in your application logic +@app.consumer(source=sqs_queue, sink=gcs_bucket) +def process(event: YourSchema) -> OutputSchema: + # Processing logic goes here + return OutputSchema(...) +``` + +#### Dependency Injection | 📖 [Docs](https://docs.launchflow.com/buildflow/introduction) + +Inject any dependency with full control over its setup and lifecycle + +```python +# Define custom dependencies +@dependency(Scope.GLOBAL) +class MyStringDependency: + def __init__(self): + self.my_string = "HELLO!" + +# Or use the prebuilt dependencies +PostgresDep = SessionDepBuilder(postgres) + +# BuildFlow handles the rest +@service.endpoint("/hello", method="GET") +def hello(db: PostgresDep, custom_dep: MyStringDependency): + with db.session as session: + user = session.query(User).first() + # Returns "HELLO! User.name" + return f"{custom_dep.my_string} {user.name}" +``` + +#### Async Runtime | 📖 [Docs](https://docs.launchflow.com/buildflow/introduction) -- Automatic [resource creation / management](https://www.buildflow.dev/docs/features/infrastructure-from-code) (Infrastructure as Code) powered by [Pulumi](https://github.com/pulumi/pulumi) (Infrastructure from Code) -- Automatic [parallelism & concurrency](https://www.buildflow.dev/docs/features/parallelism) powered by [Ray](https://github.com/ray-project/ray) -- [Dynamic autoscaling](https://www.buildflow.dev/docs/features/autoscaling): scale up during high traffic / reduce costs during low traffic +Scale out parallel tasks across your cluster with [Ray](https://docs.ray.io/en/latest/index.html) or any other async framework. -## Installation +```python +@ray.remote +def long_task(elem): + time.sleep(10) + return elem + +@app.consumer(PubSubSubscription(...), BigQueryTable(...)) +def my_consumer(elem): + # Tasks are automatically parallelized across your cluster + return await long_task.remote(elem) +``` + +## ⚙️ Installation ```bash pip install buildflow @@ -26,7 +110,7 @@ pip install buildflow #### Pulumi Installation -BuildFlow uses Pulumi to manage resources used by your BuildFlow Nodes and Processors. To install Pulumi visit: https://www.pulumi.com/docs/install/ +BuildFlow uses Pulumi to manage resources used by your application. To install Pulumi visit: https://www.pulumi.com/docs/install/ Installing Pulumi unlocks: @@ -34,14 +118,15 @@ Installing Pulumi unlocks: - full access to Pulumi API / CLI - fine-grained control over Pulumi Stacks & Resources -## Quick Links +## 📑 Resources + +
-- **Docs**: https://www.buildflow.dev/docs -- **Walkthroughs**: https://www.buildflow.dev/docs/walkthroughs/realtime-image-classification -- **Slack**: https://join.slack.com/t/launchflowusers/shared_invite/zt-27wlowsza-Uiu~8hlCGkvPINjmMiaaMQ -- **Contribute**: https://www.buildflow.dev/docs/developers/contribute +📖 [Docs](https://docs.launchflow.com/buildflow/introduction)   |   ⚡ [Quickstart](https://docs.launchflow.com/buildflow/quickstart)   |   👋 [Slack](https://join.slack.com/t/launchflowusers/shared_invite/zt-27wlowsza-Uiu~8hlCGkvPINjmMiaaMQ)   |   🌟 [Contribute](https://docs.launchflow.com/buildflow/developers/contribute)   |   🚀 [Deployment](https://www.launchflow.com/)   -## Code Health Checks +
+ +## 🩺 Code Health Checks We use [black](https://github.com/psf/black) and [ruff](https://github.com/charliermarsh/ruff) with [pre-commit](https://pre-commit.com/) hooks to perform health checks. To setup these locally: @@ -51,3 +136,7 @@ To setup these locally: - Check if pre-commit is installed correctly by running `pre-commit --version` - Setup pre-commit to run before every commit on staged changes by running `pre-commit install` - Pre-commit can also be ran manually as `pre-commit run --all-files` + +## 📜 License + +BuildFlow is open-source and licensed under the [Apache License 2.0](LICENSE). We welcome contributions, see our [CONTRIBUTING.md](CONTRIBUTING.md) file for details. diff --git a/docs/images/buildflow.png b/docs/images/buildflow.png new file mode 100644 index 00000000..fa5f2b7d Binary files /dev/null and b/docs/images/buildflow.png differ