This is an automated email from the ASF dual-hosted git repository. bossenti pushed a commit to branch chore/improve-getting-started-python in repository https://gitbox.apache.org/repos/asf/streampipes.git
commit b231f2c4f1eb03f9e7606bd2b631fb891512b626 Author: bossenti <[email protected]> AuthorDate: Sat Feb 18 21:23:29 2023 +0100 chore(python-docs): improve getting started section Signed-off-by: bossenti <[email protected]> --- .../docs/getting-started/developing.md | 90 ++++++++++++++++++++++ .../docs/getting-started/first-steps.md | 68 ++++++++++++++++ .../docs/getting-started/installation.md | 43 ----------- streampipes-client-python/mkdocs.yml | 3 +- 4 files changed, 160 insertions(+), 44 deletions(-) diff --git a/streampipes-client-python/docs/getting-started/developing.md b/streampipes-client-python/docs/getting-started/developing.md new file mode 100644 index 000000000..7a62350b1 --- /dev/null +++ b/streampipes-client-python/docs/getting-started/developing.md @@ -0,0 +1,90 @@ +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + ~ +--> + +## 📖 Development Guide +This document describes how to easily set up your local dev environment to work on the +StreamPipes Python client 🐍. +<br> + +### 🚀 First Steps + +1) **Set up your Python environment** + +Create a virtual Python environment with a tool of your choice. +As a next step, install all required dependencies for the development, e.g., with `pip`: + +```bash +pip install .[dev] # or alternatively: pip install .[all] to include dependencies for building the docs as well +``` + +In case you are on macOS and using `zsh` the following should work for you: +```bash +pip install ."[dev]" +``` +<br> + +2) **Install pre-commit hook** + +The pre-commit hook is run before every commit and takes care about code style, +linting, type hints, import sorting, etc. It will stop your commit in case the changes do not apply the expected format. +Always check to have the recent version of the pre-commit hook installed otherwise the CI build might fail. +If you are interested you can have a deeper look on the underlying library: [pre-commit](https://pre-commit.com/). + +```bash +pre-commit install +``` +The definition of the pre-commit hook can be found in [.pre-commit-config.yaml](.pre-commit-config.yaml). + +<br> + +### 👏 Conventions +Below we list some conventions that we have agreed on for creating the StreamPipes Python client. +Please comply to them when you plan to contribute to this project. +If you have any other suggestions or would like to discuss them, we would be happy to hear from you on our mailing list [[email protected]](mailto:[email protected]). + +1) **Use `numpy` style for Python docstrings** 📄 <br> +Please stick to the `numpy` style when writing docstrings, as we require this for generating our documentation. + + +2) **Provide tests** ✅ <br> +We are aiming for broad test coverage for the Python client and +have therefore set a requirement of at least 90% unit test coverage. +Therefore, please remember to write (unit) tests already during development. +If you have problems with writing tests, don't hesitate to ask us for help directly in the PR or +even before that via our mailing list (see above). + + +<!--- +TODO: replace link to java file by link to documentation +---> +3) **Build a similar API as the Java client provides** 🔄 <br> +Whenever possible, please try to develop the API of the Python library the same as the [Java client](../streampipes-client/src/main/java/org/apache/streampipes/client/StreamPipesClient.java) or Java SDK. +By doing so, we would like to provide a consistent developer experience and the basis for automated testing in the future. + +--- +## 👨💻 Contributing +*Before opening a pull request*, review the [Get Involved](https://streampipes.apache.org/getinvolved.html) page. +It lists information that is required for contributing to StreamPipes. + +When you contribute code, you affirm that the contribution is your original work and that you +license the work to the project under the project's open source license. Whether or not you +state this explicitly, by submitting any copyrighted material via pull request, email, or +other means you agree to license the material under the project's open source license and +warrant that you have the legal authority to do so. + +--- \ No newline at end of file diff --git a/streampipes-client-python/docs/getting-started/first-steps.md b/streampipes-client-python/docs/getting-started/first-steps.md new file mode 100644 index 000000000..92975c39e --- /dev/null +++ b/streampipes-client-python/docs/getting-started/first-steps.md @@ -0,0 +1,68 @@ +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + ~ +--> + +## 📚 Installation + +The StreamPipes Python library is meant to work with Python 3.8 and above. Installation can be done via `pip`: +You can install the latest development version from GitHub, as so: + +```bash +pip install streampipes +# if you want to have the current development state you can also execute +pip install git+https://github.com/apache/streampipes.git#subdirectory=streampipes-client-python +``` + +## ⬆️ Setting up StreamPipes +When working with the StreamPipes Python library it is inevitable to have a running StreamPipes instance to connect and interact with. +In case you don't have a running instance at hand, you can easily set up one on your local machine. +Hereby you need to consider that StreamPipes supports different message broker (e.g., Kafka, NATS). +Although the Python library aims to support all of them equally, we encourage you to run StreamPipes with the NATS protocol as the messaging layer. +If you are using a different messaging broker and experience a problem, please do not hesitate to contact us. +In case you are unsure if it is indeed a bug, please feel free to start a [discussion](https://github.com/apache/streampipes/discussions) on GitHub. +Alternatively, file us a bug in form of a GitHub [issue](https://github.com/apache/streampipes/issues/new/choose). +<br> +The following shows how you can set up a StreamPipes instance that uses [NATS](https://docs.nats.io/) as messaging layer. + +### 🐳 Start StreamPipes via Docker Compose +The easiest and therefore recommend way to get StreamPipes started is by using [docker compose](https://docs.docker.com/compose/). +Therefore, you need Docker running. You can check if Docker is ready on your machine by executing. +````bash +docker ps +```` +If this results in an output similar to the following, Docker is ready to continue. +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +... ... ... ... ... ... ... +``` +Otherwise, you need to start docker first. + +Please read the full guide on how to start StreamPipes with `docker compose` [here](https://github.com/apache/streampipes/blob/dev/installer/compose/README.md). +So in our scenario, we will go with `docker-compose.nats.yml` to use NATS as messaging backend. +Thereby, when running locally, we need to add the following port mapping entry to `nats.ports`: +```yaml +- 4222:4222 +``` + +After this modification is applied, StreamPipes can simply be started with this command: +```bash +docker-compose -f docker-compose.nats.yml up -d +``` + +Once all services are started, you can access StreamPipes via `http://localhost`. + +Have fun discovering StreamPipes and our Python library 🚀 diff --git a/streampipes-client-python/docs/getting-started/installation.md b/streampipes-client-python/docs/getting-started/installation.md deleted file mode 100644 index a5145d42a..000000000 --- a/streampipes-client-python/docs/getting-started/installation.md +++ /dev/null @@ -1,43 +0,0 @@ -<!-- - ~ Licensed to the Apache Software Foundation (ASF) under one or more - ~ contributor license agreements. See the NOTICE file distributed with - ~ this work for additional information regarding copyright ownership. - ~ The ASF licenses this file to You under the Apache License, Version 2.0 - ~ (the "License"); you may not use this file except in compliance with - ~ the License. You may obtain a copy of the License at - ~ - ~ http://www.apache.org/licenses/LICENSE-2.0 - ~ - ~ Unless required by applicable law or agreed to in writing, software - ~ distributed under the License is distributed on an "AS IS" BASIS, - ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - ~ See the License for the specific language governing permissions and - ~ limitations under the License. - ~ ---> - -# 📚 Installation - -The StreamPipes Python library is meant to work with Python 3.8 and above. Installation can be done via `pip`: -You can install the latest development version from GitHub, as so: - -```bash -pip install streampipes -# if you want to have the current development state you can also execute -pip install git+https://github.com/apache/streampipes.git#subdirectory=streampipes-client-python -``` - ---- -# 👨💻 Contributing -*Before opening a pull request*, review the [Get Involved](https://streampipes.apache.org/getinvolved.html) page. -It lists information that is required for contributing to StreamPipes. - -When you contribute code, you affirm that the contribution is your original work and that you -license the work to the project under the project's open source license. Whether or not you -state this explicitly, by submitting any copyrighted material via pull request, email, or -other means you agree to license the material under the project's open source license and -warrant that you have the legal authority to do so. - -For more information on how to start with the Python client, click [here](https://github.com/apache/streampipes/blob/dev/streampipes-client-python/DEVELOPMENT.md). - ---- \ No newline at end of file diff --git a/streampipes-client-python/mkdocs.yml b/streampipes-client-python/mkdocs.yml index edc04206a..e73ef072c 100644 --- a/streampipes-client-python/mkdocs.yml +++ b/streampipes-client-python/mkdocs.yml @@ -78,7 +78,8 @@ extra_css: nav: - Home: index.md - Getting Started: - - Installation: getting-started/installation.md + - First Steps: getting-started/first-steps.md + - Developing & Contributing: getting-started/developing.md - Quickstart: getting-started/quickstart.md - Examples: - Introduction to the StreamPipes Python Client: examples/1-introduction-to-streampipes-python-client.ipynb
