Skip to content

Commit 71b53cf

Browse files
rakeshcusatrakeshcusat
committed
Add Pypi friendly documentation
1 parent 154bd93 commit 71b53cf

File tree

3 files changed

+145
-7
lines changed

3 files changed

+145
-7
lines changed

‎README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ Currently, this repository contains SDKs for Java, Python and Go.
6161

6262
Have ideas for new SDKs or DSLs? See the [sdk-ideas label](https://github.com/apache/beam/issues?q=is%3Aopen+is%3Aissue+label%3Asdk-ideas).
6363

64+
#### Specific SDK Readmes
65+
66+
* [Python SDK readme](./sdks/python/README.md)
67+
6468
### Runners
6569

6670
Beam supports executing programs on multiple distributed processing backends through PipelineRunners. Currently, the following PipelineRunners are available:

‎sdks/python/README.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Apache Beam
2+
3+
[Apache Beam](http://beam.apache.org/) is a unified model for defining both batch and streaming data-parallel processing pipelines, as well as a set of language-specific SDKs for constructing pipelines and Runners for executing them on distributed processing backends, including [Apache Flink](http://flink.apache.org/), [Apache Spark](http://spark.apache.org/), [Google Cloud Dataflow](http://cloud.google.com/dataflow/), and [Hazelcast Jet](https://jet.hazelcast.org/).
4+
5+
6+
## Overview
7+
8+
Beam provides a general approach to expressing [embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel) data processing pipelines and supports three categories of users, each of which have relatively disparate backgrounds and needs.
9+
10+
1. _End Users_: Writing pipelines with an existing SDK, running it on an existing runner. These users want to focus on writing their application logic and have everything else just work.
11+
2. _SDK Writers_: Developing a Beam SDK targeted at a specific user community (Java, Python, Scala, Go, R, graphical, etc). These users are language geeks and would prefer to be shielded from all the details of various runners and their implementations.
12+
3. _Runner Writers_: Have an execution environment for distributed processing and would like to support programs written against the Beam Model. Would prefer to be shielded from details of multiple SDKs.
13+
14+
15+
### The Beam Model
16+
17+
The model behind Beam evolved from several internal Google data processing projects, including [MapReduce](http://research.google.com/archive/mapreduce.html), [FlumeJava](http://research.google.com/pubs/pub35650.html), and [Millwheel](http://research.google.com/pubs/pub41378.html). This model was originally known as the “[Dataflow Model](http://www.vldb.org/pvldb/vol8/p1792-Akidau.pdf)”.
18+
19+
To learn more about the Beam Model (though still under the original name of Dataflow), see the World Beyond Batch: [Streaming 101](https://www.oreilly.com/ideas/the-world-beyond-batch-streaming-101) and [Streaming 102](https://www.oreilly.com/ideas/the-world-beyond-batch-streaming-102) posts on O’Reilly’s Radar site, and the [VLDB 2015 paper](http://www.vldb.org/pvldb/vol8/p1792-Akidau.pdf).
20+
21+
The key concepts in the Beam programming model are:
22+
23+
* `PCollection`: represents a collection of data, which could be bounded or unbounded in size.
24+
* `PTransform`: represents a computation that transforms input PCollections into output PCollections.
25+
* `Pipeline`: manages a directed acyclic graph of PTransforms and PCollections that is ready for execution.
26+
* `PipelineRunner`: specifies where and how the pipeline should execute.
27+
28+
### Runners
29+
30+
Beam supports executing programs on multiple distributed processing backends through PipelineRunners. Currently, the following PipelineRunners are available:
31+
32+
- The `DirectRunner` runs the pipeline on your local machine.
33+
- The `PrismRunner` runs the pipeline on your local machine using Beam Portability.
34+
- The `DataflowRunner` submits the pipeline to the [Google Cloud Dataflow](http://cloud.google.com/dataflow/).
35+
- The `FlinkRunner` runs the pipeline on an Apache Flink cluster. The code has been donated from [dataArtisans/flink-dataflow](https://github.com/dataArtisans/flink-dataflow) and is now part of Beam.
36+
- The `SparkRunner` runs the pipeline on an Apache Spark cluster.
37+
- The `JetRunner` runs the pipeline on a Hazelcast Jet cluster. The code has been donated from [hazelcast/hazelcast-jet](https://github.com/hazelcast/hazelcast-jet) and is now part of Beam.
38+
- The `Twister2Runner` runs the pipeline on a Twister2 cluster. The code has been donated from [DSC-SPIDAL/twister2](https://github.com/DSC-SPIDAL/twister2) and is now part of Beam.
39+
40+
Have ideas for new Runners? See the [runner-ideas label](https://github.com/apache/beam/issues?q=is%3Aopen+is%3Aissue+label%3Arunner-ideas).
41+
42+
43+
## Get started with the Python SDK
44+
45+
Get started with the [Beam Python SDK quickstart](/get-started/quickstart-py) to set up your Python development environment, get the Beam SDK for Python, and run an example pipeline. Then, read through the [Beam programming guide](/documentation/programming-guide) to learn the basic concepts that apply to all SDKs in Beam.
46+
47+
See the [Python API reference](https://beam.apache.org/releases/pydoc/) for more information on individual APIs.
48+
49+
## Python streaming pipelines
50+
51+
Python [streaming pipeline execution](/documentation/sdks/python-streaming)
52+
is available (with some [limitations](/documentation/sdks/python-streaming/#unsupported-features))
53+
starting with Beam SDK version 2.5.0.
54+
55+
## Python type safety
56+
57+
Python is a dynamically-typed language with no static type checking. The Beam SDK for Python uses type hints during pipeline construction and runtime to try to emulate the correctness guarantees achieved by true static typing. [Ensuring Python Type Safety](/documentation/sdks/python-type-safety) walks through how to use type hints, which help you to catch potential bugs up front with the [Direct Runner](/documentation/runners/direct/).
58+
59+
## Managing Python pipeline dependencies
60+
61+
When you run your pipeline locally, the packages that your pipeline depends on are available because they are installed on your local machine. However, when you want to run your pipeline remotely, you must make sure these dependencies are available on the remote machines. [Managing Python Pipeline Dependencies](/documentation/sdks/python-pipeline-dependencies) shows you how to make your dependencies available to the remote workers.
62+
63+
## Developing new I/O connectors for Python
64+
65+
The Beam SDK for Python provides an extensible API that you can use to create
66+
new I/O connectors. See the [Developing I/O connectors overview](/documentation/io/developing-io-overview)
67+
for information about developing new I/O connectors and links to
68+
language-specific implementation guidance.
69+
70+
## Making machine learning inferences with Python
71+
72+
To integrate machine learning models into your pipelines for making inferences, use the RunInference API for PyTorch and Scikit-learn models. If you are using TensorFlow models, you can make use of the
73+
[library from `tfx_bsl`](https://github.com/tensorflow/tfx-bsl/tree/master/tfx_bsl/beam).
74+
75+
You can create multiple types of transforms using the RunInference API: the API takes multiple types of setup parameters from model handlers, and the parameter type determines the model implementation. For more information,
76+
see [About Beam ML](/documentation/ml/about-ml).
77+
78+
[TensorFlow Extended (TFX)](https://www.tensorflow.org/tfx) is an end-to-end platform for deploying production ML pipelines. TFX is integrated with Beam. For more information, see [TFX user guide](https://www.tensorflow.org/tfx/guide).
79+
80+
## Python multi-language pipelines quickstart
81+
82+
Apache Beam lets you combine transforms written in any supported SDK language and use them in one multi-language pipeline. To learn how to create a multi-language pipeline using the Python SDK, see the [Python multi-language pipelines quickstart](/documentation/sdks/python-multi-language-pipelines).
83+
84+
## Unrecoverable Errors in Beam Python
85+
86+
Some common errors can occur during worker start-up and prevent jobs from starting. To learn about these errors and how to troubleshoot them in the Python SDK, see [Unrecoverable Errors in Beam Python](/documentation/sdks/python-unrecoverable-errors).
87+
88+
## 📚 Learn More
89+
90+
Here are some resources actively maintained by the Beam community to help you get started:
91+
<table>
92+
<thead>
93+
<tr>
94+
<th><b>Resource</b></th>
95+
<th><b>Details</b></th>
96+
</tr>
97+
</thead>
98+
<tbody>
99+
<tr>
100+
<td><a href="https://beam.apache.org" target="_blank" rel="noopener noreferrer">Apache Beam Website</a></td>
101+
<td>Our website discussing the project, and it's specifics.</td>
102+
</tr>
103+
<tr>
104+
<td><a href="https://beam.apache.org/get-started/quickstart-py" target="_blank" rel="noopener noreferrer">Python Quickstart</a></td>
105+
<td>A guide to getting started with the Python SDK.</td>
106+
</tr>
107+
<tr>
108+
<td><a href="https://tour.beam.apache.org/" target="_blank" rel="noopener noreferrer">Tour of Beam </a></td>
109+
<td>A comprehensive, interactive learning experience covering Beam concepts in depth.</td>
110+
</tr>
111+
<tr>
112+
<td><a href="https://www.cloudskillsboost.google/course_templates/724" target="_blank" rel="noopener noreferrer">Beam Quest </a></td>
113+
<td>A certification granted by Google Cloud, certifying proficiency in Beam.</td>
114+
</tr>
115+
<tr>
116+
<td><a href="https://s.apache.org/beam-community-metrics" target="_blank" rel="noopener noreferrer">Community Metrics </a></td>
117+
<td>Beam's Git Community Metrics.</td>
118+
</tr>
119+
</tbody>
120+
</table>
121+
122+
123+
## Contribution
124+
125+
Instructions for building and testing Beam itself
126+
are in the [contribution guide](../../CONTRIBUTING.md).
127+
128+
## Contact Us
129+
130+
To get involved with Apache Beam:
131+
132+
* [Subscribe to](https://beam.apache.org/community/contact-us/#:~:text=Subscribe%20and%20Unsubscribe) or e-mail the [user@beam.apache.org](http://mail-archives.apache.org/mod_mbox/beam-user/) list.
133+
* [Subscribe to](https://beam.apache.org/community/contact-us/#:~:text=Subscribe%20and%20Unsubscribe) or e-mail the [dev@beam.apache.org](http://mail-archives.apache.org/mod_mbox/beam-dev/) list.
134+
* [Join ASF Slack](https://s.apache.org/slack-invite) on [#beam channel](https://s.apache.org/beam-slack-channel)
135+
* [Report an issue](https://github.com/apache/beam/issues/new/choose).

‎sdks/python/setup.py

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,12 +91,6 @@ def get_version():
9191
PACKAGE_AUTHOR = 'Apache Software Foundation'
9292
PACKAGE_EMAIL = 'dev@beam.apache.org'
9393
PACKAGE_KEYWORDS = 'apache beam'
94-
PACKAGE_LONG_DESCRIPTION = '''
95-
Apache Beam is a unified programming model for both batch and streaming
96-
data processing, enabling efficient execution across diverse distributed
97-
execution engines and providing extensibility points for connecting to
98-
different technologies and user communities.
99-
'''
10094

10195
RECOMMENDED_MIN_PIP_VERSION = '19.3.0'
10296
try:
@@ -311,13 +305,18 @@ def get_portability_package_data():
311305
])
312306
else:
313307
extensions = []
308+
309+
long_description = ((Path(__file__).parent / "README.md") # pragma: no cover
310+
.read_text(encoding='utf-8')) # pragma: no cover
311+
314312
# Keep all dependencies inlined in the setup call, otherwise Dependabot won't
315313
# be able to parse it.
316314
setuptools.setup(
317315
name=PACKAGE_NAME,
318316
version=PACKAGE_VERSION,
319317
description=PACKAGE_DESCRIPTION,
320-
long_description=PACKAGE_LONG_DESCRIPTION,
318+
long_description=long_description,
319+
long_description_content_type='text/markdown',
321320
url=PACKAGE_URL,
322321
download_url=PACKAGE_DOWNLOAD_URL,
323322
author=PACKAGE_AUTHOR,

0 commit comments

Comments
 (0)