From 517515408a8bc61de753039103e8ea461919a84e Mon Sep 17 00:00:00 2001 From: veit Date: Mon, 26 Oct 2020 13:24:08 +0100 Subject: [PATCH] Switch to English documentation --- README.rst | 45 +- docs/clean-prep/dask-pipeline.ipynb | 20 +- docs/clean-prep/deduplicate.ipynb | 24 +- docs/clean-prep/engarde.ipynb | 18 +- docs/clean-prep/hypothesis.ipynb | 14 +- docs/clean-prep/index.rst | 12 +- docs/clean-prep/nulls.ipynb | 20 +- .../scikit-learn-reprocessing.ipynb | 10 +- docs/clean-prep/string-matching.ipynb | 24 +- docs/clean-prep/tdda.ipynb | 12 +- docs/clean-prep/voluptuous.ipynb | 24 +- docs/conf.py | 8 +- docs/data-rw/beautifulsoup.ipynb | 21 +- docs/data-rw/glossary.rst | 416 ++++++++-------- docs/data-rw/index.rst | 35 +- docs/data-rw/intake/data-engineers.ipynb | 26 +- docs/data-rw/intake/data-scientists.ipynb | 26 +- docs/data-rw/intake/gui.ipynb | 44 +- docs/data-rw/intake/index.rst | 6 +- docs/data-rw/intake/install.rst | 21 +- docs/data-rw/nosql/column-oriented-db.rst | 60 ++- docs/data-rw/nosql/document-oriented-db.rst | 63 ++- docs/data-rw/nosql/graph-db.rst | 121 +++-- docs/data-rw/nosql/index.rst | 34 +- docs/data-rw/nosql/key-value-store.rst | 61 ++- docs/data-rw/nosql/object-db.rst | 104 ++-- docs/data-rw/nosql/xml-db.rst | 37 +- docs/data-rw/overview.rst | 35 +- docs/data-rw/postgresql/alembic.rst | 101 ++-- docs/data-rw/postgresql/db-api.rst | 48 +- docs/data-rw/postgresql/fdw.rst | 91 ++-- docs/data-rw/postgresql/index.rst | 96 ++-- docs/data-rw/postgresql/orm.rst | 41 +- docs/data-rw/postgresql/plang.rst | 18 +- docs/data-rw/postgresql/postgis/index.rst | 35 +- docs/data-rw/postgresql/postgis/install.rst | 22 +- docs/data-rw/postgresql/postgis/load.rst | 65 ++- .../data-rw/postgresql/postgis/optimising.rst | 28 +- docs/data-rw/postgresql/psycopg2.rst | 18 +- docs/data-rw/postgresql/sec.rst | 100 ++-- docs/data-rw/postgresql/sqlalchemy.rst | 28 +- docs/data-rw/requests/index.rst | 6 +- docs/data-rw/requests/module.ipynb | 14 +- docs/data-rw/requests/requests.ipynb | 39 +- docs/first-steps/create-notebook.rst | 131 +++--- docs/first-steps/example.ipynb | 38 +- docs/first-steps/index.rst | 6 +- docs/first-steps/install.rst | 76 ++- docs/genindex.rst | 4 +- docs/index.rst | 15 +- docs/intro.rst | 188 ++++---- docs/productive/documenting/docstrings.rst | 80 ++-- docs/productive/documenting/extensions.rst | 58 ++- docs/productive/documenting/index.rst | 90 ++-- docs/productive/documenting/intersphinx.rst | 72 ++- docs/productive/documenting/rest.rst | 78 ++- docs/productive/documenting/start.rst | 14 +- docs/productive/dvc/dag.rst | 12 +- docs/productive/dvc/index.rst | 88 ++-- docs/productive/dvc/init.rst | 90 ++-- docs/productive/dvc/integration.rst | 15 +- docs/productive/dvc/metrics.rst | 29 +- docs/productive/dvc/params.rst | 32 +- docs/productive/dvc/pipeline.rst | 55 +-- docs/productive/dvc/reproduce.rst | 20 +- docs/productive/envs/devpi.rst | 4 +- docs/productive/envs/glossary.rst | 203 ++++---- docs/productive/envs/index.rst | 15 +- docs/productive/envs/pipenv/deterministic.rst | 17 +- docs/productive/envs/pipenv/index.rst | 6 +- docs/productive/envs/pipenv/install.rst | 81 ++-- docs/productive/envs/pipenv/spack.rst | 22 +- docs/productive/envs/pipenv/use.rst | 260 +++++----- docs/productive/envs/pipenv/workflows.rst | 62 ++- .../envs/spack/build-automatisation.rst | 31 +- .../envs/spack/combinatorial-builds.rst | 112 +++-- docs/productive/envs/spack/envs.rst | 113 +++-- docs/productive/envs/spack/future.rst | 12 +- docs/productive/envs/spack/index.rst | 43 +- docs/productive/envs/spack/install.rst | 83 ++-- docs/productive/envs/spack/mirrors.rst | 51 +- docs/productive/envs/spack/use.rst | 56 ++- docs/productive/envs/spack/usecase1.rst | 23 +- docs/productive/envs/spack/usecase2.rst | 4 +- docs/productive/git/best-practices.rst | 173 ++++--- docs/productive/git/branching.rst | 46 +- docs/productive/git/glossary.rst | 34 +- docs/productive/git/index.rst | 21 +- docs/productive/git/install-config.rst | 127 +++-- docs/productive/git/jupyter-config.rst | 102 ++-- docs/productive/git/log.rst | 43 +- docs/productive/git/pre-commit.rst | 93 ++-- docs/productive/git/reverting.rst | 30 +- docs/productive/git/tagging.rst | 14 +- docs/productive/git/tools.rst | 21 +- docs/productive/git/work.rst | 75 +-- .../git/workflows/branches-merge-requests.rst | 111 ++--- .../git/workflows/deploy-branches.rst | 62 ++- .../git/workflows/feature-branches.rst | 28 +- docs/productive/git/workflows/git-flow.rst | 40 +- docs/productive/git/workflows/index.rst | 8 +- docs/productive/git/workflows/monorepos.rst | 91 ++-- docs/productive/git/working-areas.rst | 24 +- docs/productive/index.rst | 49 +- docs/productive/licensing.rst | 203 ++++---- docs/productive/logging.ipynb | 80 ++-- .../packaging/binary-extensions.rst | 445 +++++++++--------- docs/productive/packaging/distribution.rst | 185 ++++---- docs/productive/packaging/example.rst | 18 +- docs/productive/packaging/index.rst | 42 +- docs/productive/packaging/next-steps.rst | 28 +- .../packaging/templating/advanced.rst | 45 +- .../packaging/templating/features.rst | 37 +- .../productive/packaging/templating/index.rst | 5 +- .../packaging/templating/install.rst | 31 +- .../packaging/templating/overview.rst | 12 +- .../packaging/templating/templates.rst | 48 +- docs/productive/packaging/upload-install.rst | 103 ++-- docs/productive/quote/authorship.rst | 10 +- docs/productive/quote/index.rst | 117 +++-- docs/productive/quote/journals.rst | 32 +- docs/productive/testing/hypothesis.rst | 34 +- docs/productive/testing/index.rst | 14 +- docs/productive/testing/ipytest.ipynb | 56 +-- docs/productive/testing/mock.rst | 39 +- docs/productive/testing/tox.rst | 36 +- docs/productive/testing/unittest.ipynb | 40 +- docs/productive/testing/unittest2.rst | 25 +- docs/refactoring/autoqual/black.rst | 30 +- docs/refactoring/autoqual/flake8.rst | 18 +- docs/refactoring/autoqual/index.rst | 12 +- docs/refactoring/autoqual/isort.rst | 20 +- docs/refactoring/autoqual/manifest.rst | 51 +- docs/refactoring/autoqual/mypy.rst | 15 +- docs/refactoring/autoqual/prettier.rst | 17 +- docs/refactoring/index.rst | 8 +- docs/refactoring/parallel/async-example.ipynb | 10 +- docs/refactoring/parallel/index.rst | 12 +- docs/refactoring/parallel/introduction.ipynb | 49 +- .../parallel/ipyparallel/asyncresult.ipynb | 18 +- .../parallel/ipyparallel/check.ipynb | 2 +- .../parallel/ipyparallel/config.rst | 29 +- .../parallel/ipyparallel/direct.ipynb | 12 +- .../parallel/ipyparallel/index.rst | 10 +- .../parallel/ipyparallel/install.rst | 6 +- .../parallel/ipyparallel/intro.rst | 104 ++-- .../parallel/ipyparallel/magics.ipynb | 28 +- .../parallel/ipyparallel/mpi.ipynb | 30 +- .../parallel/ipyparallel/task.ipynb | 46 +- .../parallel/multiprocessing.ipynb | 50 +- .../parallel/threading-example.ipynb | 58 +-- .../parallel/threading-forking-combined.ipynb | 8 +- docs/viz/index.rst | 6 +- docs/web/dashboards/appmode/index.rst | 51 +- docs/web/dashboards/index.rst | 35 +- .../dashboards/jupyter-dashboards/index.rst | 49 +- .../dashboards/jupyter-dashboards/install.rst | 4 +- .../matplotlib-example.ipynb | 10 +- .../web/dashboards/jupyter-dashboards/use.rst | 37 +- docs/web/dashboards/panel/deploy.ipynb | 96 ++-- docs/web/dashboards/panel/index.rst | 9 +- docs/web/dashboards/panel/install.rst | 20 +- docs/web/dashboards/panel/interact.ipynb | 45 +- docs/web/dashboards/panel/overview.ipynb | 60 +-- docs/web/dashboards/panel/params.ipynb | 71 +-- docs/web/dashboards/panel/pipelines.ipynb | 38 +- docs/web/dashboards/panel/style.ipynb | 42 +- docs/web/dashboards/panel/templates.ipynb | 18 +- docs/web/dashboards/panel/widgets.ipynb | 115 ++--- .../voila/bqplot_vuetify_example.ipynb | 12 +- docs/web/dashboards/voila/index.rst | 66 ++- docs/web/dashboards/voila/install.rst | 50 +- docs/web/dashboards/voila/templating.rst | 82 ++-- docs/web/index.rst | 18 +- docs/workspace/index.rst | 10 +- docs/workspace/ipython/debugging.ipynb | 56 +-- docs/workspace/ipython/display.ipynb | 38 +- docs/workspace/ipython/extensions.rst | 51 +- docs/workspace/ipython/importing.ipynb | 40 +- docs/workspace/ipython/index.rst | 13 +- docs/workspace/ipython/magics.ipynb | 46 +- docs/workspace/ipython/profiling.ipynb | 88 ++-- docs/workspace/ipython/shell.ipynb | 12 +- docs/workspace/ipython/start.rst | 17 +- docs/workspace/jupyter/hub/config.rst | 72 ++- docs/workspace/jupyter/hub/index.rst | 7 +- docs/workspace/jupyter/hub/install.rst | 32 +- .../jupyter/hub/nbviewer-service.rst | 23 +- docs/workspace/jupyter/index.rst | 54 +-- .../jupyter/ipywidgets/custom-widget.ipynb | 51 +- .../jupyter/ipywidgets/embedding.rst | 107 +++-- .../jupyter/ipywidgets/examples.ipynb | 26 +- docs/workspace/jupyter/ipywidgets/index.rst | 7 +- .../jupyter/ipywidgets/libs/index.rst | 39 +- .../jupyter/ipywidgets/libs/ipycanvas.ipynb | 139 +++--- .../jupyter/ipywidgets/libs/ipympl.ipynb | 14 +- .../jupyter/ipywidgets/libs/ipysheet.ipynb | 16 +- .../jupyter/ipywidgets/libs/ipyvuetify.ipynb | 36 +- .../jupyter/ipywidgets/libs/ipywebrtc.ipynb | 24 +- .../jupyter/ipywidgets/libs/qgrid.ipynb | 32 +- .../jupyter/ipywidgets/widget-events.ipynb | 51 +- .../jupyter/ipywidgets/widget-list.ipynb | 112 ++--- docs/workspace/jupyter/kernels/index.rst | 14 +- docs/workspace/jupyter/kernels/install.rst | 84 ++-- docs/workspace/jupyter/kernels/python2.rst | 4 +- docs/workspace/jupyter/kernels/python38.ipynb | 54 +-- docs/workspace/jupyter/kernels/python39.ipynb | 59 +-- docs/workspace/jupyter/kernels/r.rst | 8 +- docs/workspace/jupyter/nbconvert.rst | 97 ++-- .../jupyter/nbextensions/create-plugin.rst | 59 ++- docs/workspace/jupyter/nbextensions/index.rst | 6 +- .../jupyter/nbextensions/install.rst | 12 +- .../jupyter/nbextensions/ipylayout.ipynb | 12 +- docs/workspace/jupyter/nbextensions/list.rst | 126 +++-- docs/workspace/jupyter/nbsphinx.rst | 140 +++--- docs/workspace/jupyter/nbviewer.rst | 43 +- docs/workspace/jupyter/notebook/config.rst | 57 ++- docs/workspace/jupyter/notebook/index.rst | 27 +- docs/workspace/jupyter/notebook/shortcuts.rst | 144 +++--- docs/workspace/jupyter/use-cases.rst | 8 +- package-lock.json | 2 +- package.json | 4 +- 222 files changed, 5376 insertions(+), 5731 deletions(-) diff --git a/README.rst b/README.rst index be6fc269..bf94b915 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -Schnelleinstieg -=============== +Quick start +=========== |Contributors| |License| |Docs| |Pyup| @@ -17,7 +17,7 @@ Schnelleinstieg Installation ------------ -#. Herunterladen und Auspacken: +#. Download and unpack: .. code-block:: console @@ -28,11 +28,11 @@ Installation creating: jupyter-tutorial-master/ … -#. Pipenv installieren +#. Install Pipenv - Siehe :doc:`Pipenv installieren ` + Pleas refer :doc:`Install Pipenv ` -#. Python-Pakete installieren: +#. Install Python packages: .. code-block:: console @@ -46,8 +46,9 @@ Installation Enabling notebook extension highlighter/highlighter... - Validating: OK -#. Javascript- und CSS-Dateien der `Jupyter Notebook Extensions - `_ installieren +#. Install the `Jupyter Notebook Extensions + ` Javascript and CSS + files: .. code-block:: console @@ -63,7 +64,7 @@ Installation Enabling notebook extension latex_envs/latex_envs... - Validating: OK -#. HTML-Dokumentation erstellen: +#. Create HTML documentation: .. code-block:: console @@ -72,17 +73,17 @@ Installation $ bin/python -m pip install -r docs/constraints.txt $ bin/sphinx-build -ab html docs/ docs/_build/ -#. PDF erstellen: +#. Create a PDF: - Für die Erstellung von PDFs benötigt ihr weitere Pakete. + For the creation of a PDF file you need additional packages. - Für Debian/Ubuntu erhaltet ihr diese mit: + For Debian/Ubuntu you get this with: .. code-block:: console $ apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended latexmk - oder für macOS mit: + or for macOS with: .. code-block:: console @@ -95,7 +96,7 @@ Installation mktexlsr: Updating /usr/local/texlive/2020/texmf-dist/ls-R... mktexlsr: Done. - Anschließend könnt ihr ein PDF generieren mit: + Then you can generate a PDF with: .. code-block:: console @@ -106,9 +107,9 @@ Installation Run 'make' in that directory to run these through (pdf)latex … - Das PDF findet ihr anschließend in ``docs/_build/latex/jupytertutorial.pdf``. + You can find the PDF at ``docs/_build/latex/jupytertutorial.pdf``. -Folge uns +Follow us --------- * `GitHub `_ @@ -118,9 +119,9 @@ Folge uns Pull-Requests ------------- -Wenn ihr Vorschläge für Verbesserungen und Ergänzungen habt, empfehle ich euch, -einen `Fork `_ meines -`GitHub-Repository `_ zu erstellen -und darin eure Änderungen vorzunehmen. Gerne dürft ihr auch einen *Pull Request* -stellen. Sofern die darin enthaltenen Änderungen klein und atomar sind, schaue ich -mir eure Vorschläge gerne an. +If you have suggestions for improvements and additions, I recommend that you +create a `Fork `_ of my `GitHub +Repository `_ and make your changes +there. . You are also welcome to make a *pull request*. If the changes +contained therein are small and atomic, I’ll be happy to look at your +suggestions. diff --git a/docs/clean-prep/dask-pipeline.ipynb b/docs/clean-prep/dask-pipeline.ipynb index a99c8170..64d90df0 100644 --- a/docs/clean-prep/dask-pipeline.ipynb +++ b/docs/clean-prep/dask-pipeline.ipynb @@ -4,28 +4,28 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Dask-Pipeline" + "# Dask pipeline" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiel: Tracking der Internationalen Raumstation mit Dask\n", + "## Example: Tracking the International Space Station with Dask\n", "\n", - "In diesem Notebook werden wir zwei APIs verwenden:\n", + "In this notebook we will be using two APIs:\n", "\n", "1. [Google Maps Geocoder](https://developers.google.com/maps/documentation/geocoding/)\n", "2. [Open Notify API for ISS location](http://api.open-notify.org/)\n", "\n", - "Wir werden sie verwenden, um den ISS-Standort und die nächste Durchlaufzeit in Bezug auf eine Liste von Städten zu verfolgen. Um unsere Diagramme zu erstellen und Daten intelligent zu parallelisieren, verwenden wir Dask, insbesondere [Dask Delayed](http://dask.pydata.org/en/latest/delayed.html)." + "We will use them to keep track of the ISS location and next lead time in relation to a list of cities. To create our diagrams and intelligently parallelise data, we use Dask, especially [Dask Delayed](http://dask.pydata.org/en/latest/delayed.html)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### 1. Importe" + "### 1. Imports" ] }, { @@ -67,9 +67,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### 3. Latitude- und Longitude-Paare aus einer Liste von Städten\n", + "### 3. Latitude and longitude pairs from a list of cities\n", "\n", - "s.a. [Location APIs](https://locationiq.org)" + "see also [Location APIs](https://locationiq.org)" ] }, { @@ -187,7 +187,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. ISS-Daten abrufen und Durchlaufzeiten der Städte ermitteln" + "## 4. Retrieve ISS data and determine lead times for cities" ] }, { @@ -309,7 +309,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Erstellen einer `delayed`-Pipeline" + "## 5. Create a `delayed` pipeline" ] }, { @@ -353,7 +353,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 6. DAG anzeigen" + "## 6. Show DAG" ] }, { diff --git a/docs/clean-prep/deduplicate.ipynb b/docs/clean-prep/deduplicate.ipynb index 67a93d95..a3d82101 100644 --- a/docs/clean-prep/deduplicate.ipynb +++ b/docs/clean-prep/deduplicate.ipynb @@ -4,18 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Daten deduplizieren\n", + "# Deduplicate data\n", "\n", - "In diesem Notebook deduplizieren wir Daten mithilfe der [Dedupe](https://dedupe.readthedocs.io/en/latest/)-Bibliothek, die ein flaches neuronales Netzwerk verwendet, um aus einem kleinen Training zu lernen.\n", + "In this notebook, we deduplicate data using the [Dedupe](https://dedupe.readthedocs.io/en/latest/) library, which uses a flat neural network to learn from a small training session.\n", "\n", - "Zudem haben dieselben Entwickler\\*innen [parserator](https://github.com/datamade/parserator) erstellt, mit dem Ihr Textfunktionen extrahieren und Eure eigenen Textextraktion trainieren könnt. " + "In addition, the same developers have created [parserator](https://github.com/datamade/parserator) with which you can extract text functions and train your own text extraction." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Importe" + "## 1. Imports" ] }, { @@ -43,7 +43,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 2. Datenqualität überprüfen" + "## 2. Check data quality" ] }, { @@ -231,9 +231,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Dedupe konfigurieren\n", + "## 3. Configure Dedupe\n", "\n", - "Nun definieren wir die Felder, auf die bei der Deduplizierung geachtet werden soll und erstellen ein neues `deduper`-Objekt:" + "Now we define the fields to be taken into account during deduplication and create a new `deduper` object:" ] }, { @@ -300,7 +300,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. Trainingsdaten erstellen" + "## 4. Create training data" ] }, { @@ -325,9 +325,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Aktives Lernen\n", + "## 5. Active learning\n", "\n", - "Wenn Dedupe ein Datensatzpaar findet, werdet Ihr gebeten, es als Duplikat zu kennzeichnen. Ihr könnt hierfürdie Tasten `y`, `n` und `u`, um Duplikate zu kennzeichnen. Drückt `f`, wenn Ihr fertig seid." + "If Dedupe finds a pair of records, you will be asked to mark it as a duplicate. You can do this using the `y`, `n` and `u` buttons to mark duplicates. Push `f` when you're done." ] }, { @@ -521,7 +521,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn Ihr fertig seid, speichert Eure Trainingsdaten:" + "When you’re done, save your training data:" ] }, { @@ -538,7 +538,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Speichert auch Eure Gewichte und Prädikate. Wenn `settings_file` bereits existiert, werden beim nächsten Durchlauf Training und aktives Lernen übersprungen:" + "Also save your weights and predicates. If `settings_file` already exists, training and active learning will be skipped in the next run:" ] }, { diff --git a/docs/clean-prep/engarde.ipynb b/docs/clean-prep/engarde.ipynb index f6634b32..0e483dba 100644 --- a/docs/clean-prep/engarde.ipynb +++ b/docs/clean-prep/engarde.ipynb @@ -4,16 +4,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Pandas DataFrame-Validierung mit Engarde\n", + "# Pandas DataFrame validation with Engarde\n", "\n", - "In diesem Notebook überprüfen wir `pandas.DataFrame`-Objekte mit der Bibliothek [engarde](https://github.com/TomAugspurger/engarde). Mit ihr könnt Ihr sowohl Decorators für Funktionen schreiben als auch integrierte Funktionen verwenden, um Euren DataFrame mit bestimmten Validierungsregeln oder -definitionen zu testen." + "In this notebook we check `pandas.DataFrame` objects with the [engarde](https://github.com/TomAugspurger/engarde) library. With it you can write decorators for functions as well as use built-in functions to test your DataFrame with certain validation rules or definitions." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Importe" + "## 1. Imports" ] }, { @@ -31,7 +31,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 2. Daten lesen" + "## 2. Read data" ] }, { @@ -47,7 +47,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Daten überprüfen" + "## 3. Check data" ] }, { @@ -189,9 +189,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Datentypen überprüfen\n", + "## Check data types\n", "\n", - "Engarde lässt uns Datentypen nachverfolgen. In einer ersten Funktion sollten wir also unsere erwarteten Ergebnisse überpfüfen." + "Engarde lets us keep track of data types. So in a first function we should check our expected results." ] }, { @@ -258,9 +258,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Entfernen ungenügender Daten\n", + "## 5. Remove insufficient data\n", "\n", - "Um Daten von schlechter Qualität zu entfernen, entfernen wir zunächst Duplikate und fehlende Einträge." + "To remove data of poor quality, we first remove duplicates and missing entries." ] }, { diff --git a/docs/clean-prep/hypothesis.ipynb b/docs/clean-prep/hypothesis.ipynb index b9331aca..fea8f1bf 100644 --- a/docs/clean-prep/hypothesis.ipynb +++ b/docs/clean-prep/hypothesis.ipynb @@ -4,16 +4,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Hypothesis: _Property_ -basiertes Testen\n", + "# Hypothesis: property based testing\n", "\n", - "In diesem Notebook verwenden wir _Property_ -basierte Tests, um Probleme in unserem Code zu finden. [Hypothesis](https://hypothesis.readthedocs.io/en/latest/) ist eine Bibliothek, die Haskells [Quickcheck](https://hackage.haskell.org/package/QuickCheck) ähnelt. Später lernen wir sie zusammen mit anderen Testbibliotheken noch genauer kennen: [Hypothesis](https://jupyter-tutorial.readthedocs.io/de/latest/productive/testing/hypothesis.html). Hypothesis kann auch Mock-Objekte und Tests für Numpy-Datentypen bereitstellen." + "In this notebook we use property based tests to find problems in our code. [Hypothesis](https://hypothesis.readthedocs.io/en/latest/) is a library similar to Haskell’s [Quickcheck](https://hackage.haskell.org/package/QuickCheck). Later we will get to know it more closely together with other test libraries: [Hypothesis](../productive/testing/hypothesis.ipynb). Hypothesis can also provide mock objects and tests for Numpy data types." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Importe" + "## 1. Imports" ] }, { @@ -31,7 +31,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 2. Bereich finden" + "## 2. Find range" ] }, { @@ -48,7 +48,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Test mit `strategies` und `given`" + "## 3. Test with `strategies` and `given`" ] }, { @@ -101,7 +101,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Test korrigieren mit `>=`" + "## 3. Correct the test with `>=`" ] }, { @@ -130,7 +130,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. Gegen Reguläre Ausdrücke prüfen" + "## 4. Check against regular expressions" ] }, { diff --git a/docs/clean-prep/index.rst b/docs/clean-prep/index.rst index 0c85de31..54d9e340 100644 --- a/docs/clean-prep/index.rst +++ b/docs/clean-prep/index.rst @@ -1,11 +1,9 @@ -Daten bereinigen und validieren -=============================== +Clean up and validate data +========================== -Im Folgenden wollen wir Euch einen praktischen Überblick über Bibliotheken und -Methoden zur `Datenbereinigung -`_ und -validierung mit Python -geben. Dabei können wir aktuell nicht intensiv auf einzelne Bibliotheken und -Werkzeuge eingehen sondern nur eine kurze Einführung geben. +In this chapter we want to give you a practical overview of libraries and +methods for `data cleansing `_ and +validation with Python. .. seealso:: diff --git a/docs/clean-prep/nulls.ipynb b/docs/clean-prep/nulls.ipynb index 6f1d437b..35bf816d 100644 --- a/docs/clean-prep/nulls.ipynb +++ b/docs/clean-prep/nulls.ipynb @@ -4,11 +4,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Verwalten von Nullen mit Pandas\n", + "# Managing missing data with pandas\n", "\n", - "In diesem Notebook werden einige Möglichkeiten zum Verwalten von Nullen mithilfe von Pandas DataFrames vorgestellt. Weitere Informationen dazu findet Ihr in der Dokumentation des Pandas: [Working with missing data](https://pandas.pydata.org/pandas-docs/stable/user_guide/missing_data.html).\n", + "This notebook introduces a few ways to manage nulls using panda’s DataFrames. Further information can be found in the documentation of the panda: [Working with missing data](https://pandas.pydata.org/pandas-docs/stable/user_guide/missing_data.html).\n", "\n", - "## Siehe auch:\n", + "## See also:\n", "\n", "* [Missing data cookbook](https://pandas.pydata.org/pandas-docs/stable/user_guide/cookbook.html#cookbook-missing-data)" ] @@ -36,7 +36,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Prüfen der Daten" + "## Check the data" ] }, { @@ -211,7 +211,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Entfernen aller Nullwerte (einschließlich des Hinweises `n/a`)" + "## Remove all null values (including the note `n/a`)" ] }, { @@ -226,7 +226,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Testen, ob wir `dropna` verwenden können" + "### Test if we can use `dropna`" ] }, { @@ -293,7 +293,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Finden aller Spalten, in denen alle Daten vorhanden sind" + "### Find all columns in which all data is present" ] }, { @@ -355,7 +355,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Finden aller Spalten, in denen Daten fehlen" + "### Finding all columns that are missing data" ] }, { @@ -437,7 +437,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Fehlende Daten durch Mehrheitswerte ersetzen" + "## Replace missing data with majority values" ] }, { @@ -526,7 +526,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Beispiel für die fehlenden Temperaturwerte" + "### Example for the missing temperature values" ] }, { diff --git a/docs/clean-prep/scikit-learn-reprocessing.ipynb b/docs/clean-prep/scikit-learn-reprocessing.ipynb index 65a3a7d9..16ca15fe 100644 --- a/docs/clean-prep/scikit-learn-reprocessing.ipynb +++ b/docs/clean-prep/scikit-learn-reprocessing.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Scikit Learn Preprocessing" + "# Scikit Learn preprocessing" ] }, { @@ -33,7 +33,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Überprüfen der Datenqualität" + "## Checking the data quality" ] }, { @@ -202,7 +202,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Fehlenden Werten den Mittelwert zuschreiben" + "## Assign the mean to missing values" ] }, { @@ -395,7 +395,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Temperaturwerte skalieren" + "## Scaling temperature values" ] }, { @@ -436,7 +436,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Skalieren mit dem `MinMaxScaler`" + "## Scaling with the `MinMaxScaler`" ] }, { diff --git a/docs/clean-prep/string-matching.ipynb b/docs/clean-prep/string-matching.ipynb index 1c8808a2..26c8e0c0 100644 --- a/docs/clean-prep/string-matching.ipynb +++ b/docs/clean-prep/string-matching.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# String-Matching\n", + "# String matching\n", "\n", - "In diesem Notebook verwenden wir die beliebte String-Matching-Bibliothek [fuzzywuzzy](https://github.com/seatgeek/fuzzywuzzy). Weitere Informationen zu den verschiedenen verfügbaren Methoden und ihren Unterschieden findet Ihr im Blogbeitrag [FuzzyWuzzy: Fuzzy String Matching in Python](https://chairnerd.seatgeek.com/fuzzywuzzy-fuzzy-string-matching-in-python/)." + "In this notebook we use the popular string matching library [fuzzywuzzy](https://github.com/seatgeek/fuzzywuzzy). For more information on the different methods available and their differences, see the blog post [FuzzyWuzzy: Fuzzy String Matching in Python](https://chairnerd.seatgeek.com/fuzzywuzzy-fuzzy-string-matching-in-python/)." ] }, { @@ -48,9 +48,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## String-Ähnlichkeit\n", + "## String similarity\n", "\n", - "Die Übereinstimmung der erstem beiden Strings `'Berlin, Germany'` und `'Berlin, Deutschland'` scheint gering:" + "The match of the first two strings and seems low: `'Berlin, Germany'` and `'Berlin, Deutschland'`:" ] }, { @@ -77,9 +77,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Partielle String-Ähnlichkeit\n", + "## Partial string similarity\n", "\n", - "Inkonsistente Teilzeichenfolgen sind ein häufiges Problem. Um dies zu umgehen, verwendet fuzzywuzzy eine Heuristik, die als _best partial_ bezeichnet wird." + "Inconsistent substrings are a common problem. To get around this, fuzzywuzzy uses a heuristic called _best partial_." ] }, { @@ -106,9 +106,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Token-Sortierung\n", + "## Token sorting\n", "\n", - "Bei der Token-Sortierung wird die betreffende Zeichenfolge mit einem Token versehen, die Token alphabetisch sortiert und anschließend wieder zu einer Zeichenfolge zusammengefügt, beispielsweise:" + "With token sorting, the relevant character sequence is provided with a token, the tokens are sorted alphabetically and then reassembled into a character sequence, for example:" ] }, { @@ -155,7 +155,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Weitere Informationen" + "## Additional Information" ] }, { @@ -171,7 +171,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Extrahieren aus einer Liste" + "## Extract from a list" ] }, { @@ -276,9 +276,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Bekannte Ports\n", + "## Known ports\n", "\n", - "FuzzyWuzzy wird auch in andere Sprachen portiert! Hier einige bekannte Ports:\n", + "FuzzyWuzzy is also ported to other languages. Here are some known ports:\n", "\n", "* Java: [xpresso](https://github.com/WantedTechnologies/xpresso)\n", "* Java: [xdrop fuzzywuzzy](https://github.com/xdrop/fuzzywuzzy)\n", diff --git a/docs/clean-prep/tdda.ipynb b/docs/clean-prep/tdda.ipynb index 45832505..75feb69c 100644 --- a/docs/clean-prep/tdda.ipynb +++ b/docs/clean-prep/tdda.ipynb @@ -6,14 +6,14 @@ "source": [ "# TDDA: Test-Driven Data Analysis\n", "\n", - "In diesem Notebook werden wir eine Python-Bibliothek [TDDA](https://github.com/tdda/tdda) genauer anschauen, die Dateneingaben (wie NumPy-Arrays oder Pandas DataFrames) verwendet und eine Reihe von _Constraints_ um diese herum erstellt. Ihr könnt dann Eure _Constraints_ speichern (JSON-Ausgabe) und neue Daten anhand der beobachteten _Constraints_ testen." + "In this notebook we will take a closer look at the Python [TDDA](https://github.com/tdda/tdda) library that takes data inputs (such as NumPy arrays or Pandas DataFrames) and creates a series of constraints around them. You can then save your constraints (JSON output) and test new data based on the observed constraints." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Importe" + "## 1. Imports" ] }, { @@ -41,7 +41,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 2. Daten überprüfen" + "## 2. Check data" ] }, { @@ -250,7 +250,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Erstellen eines _constraint_-Objekt mit `discover_constraints`" + "## 3. Create a constraint object with `discover_constraints`" ] }, { @@ -313,7 +313,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. Schreiben der _Constraints_ in eine Datei" + "## 4. Writing the constraints to a file" ] }, { @@ -413,7 +413,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Überprüfen von Dataframes mit `verify_df`" + "## 5. Checking dataframes with `verify_df`" ] }, { diff --git a/docs/clean-prep/voluptuous.ipynb b/docs/clean-prep/voluptuous.ipynb index e76cb89e..9744ec83 100644 --- a/docs/clean-prep/voluptuous.ipynb +++ b/docs/clean-prep/voluptuous.ipynb @@ -4,16 +4,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Datenvalidierung mit Voluptuous (Schemadefinitionen)\n", + "# Data validation with voluptuous (schema definitions)\n", "\n", - "In diesem Notebook verwenden wir [Voluptuous](https://github.com/alecthomas/voluptuous), um Schemata für unsere Daten zu definieren. Wir können dann die Schemaprüfung an verschiedenen Stellen unserer Bereinigung verwenden, um sicherzustellen, dass wir die Kriterien erfüllen. Schließllich können wir Ausnahmen für die Schemaüberprüfung verwenden, um unreine oder ungültige Daten zu markieren, beiseite zu legen oder zu entfernen." + "In this notebook we use [Voluptuous](https://github.com/alecthomas/voluptuous), to define schemas for our data. We can then use the schema checker at various points in our cleanup to make sure we meet the criteria. Finally, we can use schema checking exceptions to mark, set aside, or remove impure or invalid data." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Importe" + "## 1. Imports" ] }, { @@ -50,7 +50,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Beispieldaten lesen" + "## 3. Read sample data" ] }, { @@ -66,7 +66,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. Daten untersuchen" + "## 4. Examine data" ] }, { @@ -215,7 +215,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Schema definieren" + "## 5. Define the scheme" ] }, { @@ -366,18 +366,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Aktuell wissen wir jedoch noch nicht, ob\n", + "However, we don’t currently know whether\n", "\n", - "* wir ein falsch definiertes Schema haben\n", - "* möglicherweise negative Werte zurückgegeben oder falsch markiert werden\n", - "* höhere Werte kombinierte Einkäufe oder Sonderverkäufe sind" + "* we have an incorrectly defined scheme\n", + "* negative values may be returned or incorrectly marked\n", + "* higher values are combined purchases or special sales" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 6. Hinzufügen einer benutzerdefinierten Validierung" + "## 6. Add a custom validation" ] }, { @@ -441,7 +441,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 7. Gültige Datumsstrukturen sind noch keine gültigen Daten" + "## 7. Valid date structures are not yet valid dates" ] }, { diff --git a/docs/conf.py b/docs/conf.py index b9e65848..b4ec5439 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ author = "Veit Schiele" # The full version, including alpha/beta/rc tags -release = "0.7.0" +release = "0.8.0" # -- General configuration --------------------------------------------------- @@ -50,7 +50,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = "de" +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -75,7 +75,7 @@ # documentation. # html_theme_options = { - "description": "Materialen für die Cusy-Schulungen zum Aufbau und zur Nutzung einer Forschungsinfrastruktur auf Basis von Jupyter Notebooks.", + "description": "Training materials for the Cusy training courses on setting up and using a research infrastructure based on Jupyter notebooks.", "fixed_sidebar": False, "show_powered_by": False, "github_user": "veit", @@ -90,7 +90,7 @@ html_sidebars = {"**": ["about.html", "searchbox.html", "navigation.html"]} # Change default HTML title -html_title = "Jupyter Tutorial 0.7.0" +html_title = "Jupyter Tutorial 0.8.0" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/data-rw/beautifulsoup.ipynb b/docs/data-rw/beautifulsoup.ipynb index 70e920c6..1b5319c0 100644 --- a/docs/data-rw/beautifulsoup.ipynb +++ b/docs/data-rw/beautifulsoup.ipynb @@ -24,16 +24,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "1. Installieren:\n", + "1. Install:\n", "\n", - " Mit [Spack](https://jupyter-tutorial.readthedocs.io/de/latest/productive/envs/spack/index.html) könnt ihr BeautifulSoup in eurem Kernel bereitstellen:\n", + " With [Spack](../productive/envs/spack/index.rst) you can provide BeautifulSoup in your kernel:\n", "\n", " ``` bash\n", "$ spack env activate python-374\n", "$ spack install py-beautifulsoup4 ^python@3.7.4%gcc@9.1.0\n", " ```\n", "\n", - " Alternativ könnt ihr BeautifulSoup auch mit anderen Paketmanagern installieren, z.B.\n", + " Alternatively, you can install BeautifulSoup with other package managers, e.g.\n", "\n", " ``` bash\n", "$ pipenv install beautifulsoup4\n", @@ -44,14 +44,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "2. Mit `r.content` können wir uns das HTML der Seite ausgeben lassen." + "2. With `r.content` we can display the HTML of the page." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "3. Als nächstes müssen wir diesen String mit BeautifulSoup in eine Python-Darstellung der Seite zerlegen:" + "3. Next we need to decompose this string into a Python representation of the page using BeautifulSoup:" ] }, { @@ -68,7 +68,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "4. Um den Code zu strukturieren, erstellen wir eine neue Funktion `get_dom` (**D**ocument **O**bject **M**odel), die den gesamten vorhergehenden Code einschließt:" + "4. To structure the code, let’s create a new function `get_dom` (**D**ocument **O**bject **M**odel) that includes all of the preceding code:" ] }, { @@ -87,10 +87,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Herausfiltern einzelner Elemente kann z.B. über CSS-Selektoren erfolgen. Diese können in einer Website ermittelt werden, indem ihr z.B. in Firefox mit der rechten Maustaste auf eine der Tabellenzellen in der ersten Spalte der Tabelle klickt. Im sich nun öffnenden *Inspector* könnt ihr das Element erneut mit der rechten Maustaste anklicken und dann *Copy → CSS Selector* auswählen. In der Zwischenablage befindet sich dann z.B.\n", - "`table.wikitable:nth-child(13) > tbody:nth-child(2) > tr:nth-child(1)`. Diesen *CSS-Selector* bereinigen wir nun, da wir weder nach dem 13. Kindelement der Tabelle `table.wikitable` noch dem 2. Kindelement in `tbody` filtern wollen sondern nur nach der 1. Spalte innerhalb von `tbody`.\n", + "The filtering out of individual elements can be done e.g. via CSS selectors. These can be determined in a website by e.g. Firefox, right-click on one of the table cells in the first column of the table. In the *Inspector* that opens you can click the element again with the right mouse button and then select *Copy → CSS Selector*. The clipboard then contains e.g. `table.wikitable:nth-child(13) > tbody:nth-child(2) > tr:nth-child(1)`. We are now cleaning up this *CSS-Selector* because we do not want to filter for the 13th child element of table `table.wikitable` or the 2nd child element in `tbody`, but only for the 1st column within `tbody`.\n", "\n", - "Schließlich lassen wir uns mit `limit=3` in diesem Notebook exemplarisch nur die ersten drei Ergebnisse anzeigen:" + "Finally, with `limit=3` in this notebook, we can only display the first three results as an example:" ] }, { @@ -115,7 +114,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir wollen jedoch nicht den gesamten HTML-Link, sondern nur dessen Textinnhalt:" + "However, we don’t want the entire HTML link, just its text content:" ] }, { @@ -142,7 +141,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Siehe auch:\n", + "## See also:\n", "\n", "* [Beautiful Soup Documentation](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)" ] diff --git a/docs/data-rw/glossary.rst b/docs/data-rw/glossary.rst index 845e0b21..836bd09e 100644 --- a/docs/data-rw/glossary.rst +++ b/docs/data-rw/glossary.rst @@ -1,106 +1,100 @@ -Glossar -======= +Glossary +======== .. glossary:: ACID - ACID ist ein Akronym für **A**\tomicity **C**\onsistency **I**\solation - **D**\urability. Sie gelten als Voraussetzung für die Verlässlichkeit - von Datenbanktransaktionen. - - Atomarität - Eine Transaktion ist eine Folge von Datenbankoperationen, die - entweder vollständig oder gar nicht ausgeführt werden. - Konsistenz - Transaktion, die nach Beendigung einen konsistenten Zustand - hinterlässt. Dabei werden vor Abschluss der Transaktion die im - Datenbankschema definierten Integritätsbedingungen überprüft. + ACID is an acronym for **A**\tomicity **C**\onsistency **I**\solation + **D**\urability. They are a prerequisite for the reliability of database + transactions. + + Atomicity + A transaction is a series of database operations that are either + carried out completely or not at all. + Consistency + Transaction that leaves a consistent state after completion. The + integrity conditions defined in the database schema are checked + before the transaction is completed. Isolation - Nebenläufige Transaktionen dürfen sich nicht beeinflussen. - Realisiert wird dies üblicherweise mit :term:`Locking`, das die - Nebenläufigkeit einschränkt. + Concurrent transactions must not influence each other. This is + usually achieved with :term:`Locking`, which restricts the + concurrency. Durability - Daten müssen nach erfolgreicher Transaktion dauerhaft in der - Datenbankgespeichert bleiben und kann z.B. durch das Schreiben - eines Transaktionslogs sichergestellt werden. + After a successful transaction, data must be permanently stored in + the database and can be secured, for example, by writing a + transaction log. BASE - BASE ist ein Akronym für **B**\asically **A**\vailable, **S**\oft State, - **E**\ventually Consistent und als Gegenbegriff zu :term:`ACID` - entstanden. + BASE is an acronym for **B**\asically **A**\vailable, **S**\oft State, + **E**\ventually Consistent and originated as the opposite of + :term:`ACID`. - Dabei wird ein sehr optimistischer Konsistenzbegriff verwendet, der ohne - :term:`Locking` auskommt. Locks sind in mehrerlei Hinsicht - problematisch, da Zugriffe nicht möglich sind, solange Datensätze durch - andere Transaktionen gesperrt sind. Zudem ist die Übereinkunft zum - Setzen eines Locks bereits sehr aufwändig. + A very optimistic concept of consistency is used that does not require + :term:`Locking`. Locks are problematic in several ways, since access is + not possible as long as data records are locked by other transactions. + In addition, the agreement to set a lock is already very complex. - Konsistenz der Daten wird als ein Zustand betrachtet, der irgendwann - erreicht werden kann. Dies ist die Idee der :term:`Eventual - Consistency`. + Data consistency is seen as a state that can be achieved at some point. + This is the idea of :term:`Eventual Consistency`. - Konkurrierende Zugriffe werden bei BASE durch :term:`MVCC – - Multiversion Concurrency Control` vermieden. Es gibt jedoch eine große - Bandbreite von Lösungen für die verschiedenen verteilten - Datenbanksysteme: + With BASE, competing access is avoided through :term:`MVCC – + Multiversion Concurrency Control` However, there is a wide range of + solutions for the various distributed database systems: * Causal Consistency - ist der Konsistenz in :term:`ACID` vergleichbar. + is comparable to the consistency in :term:`ACID`. * Read Your Writes * Session Consistency * Monotonic Read Consistency * Monotonic Write Consistency - CAP-Theorem - CAP ist ein Akronym für **C**\onsistency, **A**\vailability - (Verfügbarkeit) und **P**\artition Tolerance (Ausfalltoleranz). Die - Erkenntnisse des CAP-Theorems spielen bei der Auswahl eines - verteilten Datenbanksystems eine zentrale Rolle. + CAP theorem + CAP is an acronym for **C**\onsistency, **A**\vailability and + **P**\artition Tolerance. The findings of the CAP theorem play a central + role in the selection of a distributed database system. - Das CAP-Theorem besagt, dass in verteilen Systemen die drei - Anforderungen Konsistenz, Verfügbarkeit und Ausfalltoleranz nicht - vollständig vereinbar und nur maximal zwei von dreien erreichbar sind. - Für jede Anwendung muss daher individuell entschieden werden, ob eine - CA-, CP-, AP-Applikation realisiert werden soll. + The CAP theorem states that in distributed systems the three + requirements of consistency, availability and failure tolerance are not + fully compatible and only a maximum of two out of three can be achieved. + Therefore it must be decided individually for each application whether a + CA, CP or AP application should be implemented. Cassandra - Cassandra ist ein :doc:`nosql/column-oriented-db`, und wurde - ursprünglich von Facebook entwickelt um Suchen im E-Mail-Engang zu - optimieren. Heute wird es unter dem Dach der `Apache Software Foundation - `_ weiterentwickelt. - - Das Datenmodell von Cassandra hat weder eine logische Struktur noch ein - Schema. Für die Modellierung wird empfohlen *«First write your queries, - then model your data»*. Meist wird dann eine *Column Family* für jede - erwartete Anfrage erstellt. Dabei werden die Daten zwar denormalisiert, - aber jede *Column Family* antwortet auf eine bestimmte Art von Anfragen. - - In Cassandra kann für jede Anfrage die Konsistenz angegeben werden. Das - ermöglicht, dass spezifische Anfragen sehr konsistent sein können - während andere die Konsistenz der Geschwindigkeit opfern. Für die - Schreibkonsistenz gibt es z.B. die folgenden vier Ebenen: + Cassandra is a :doc:`nosql/column-oriented-db`, and was originally + developed by Facebook to optimise searches in email. Today it is further + developed under the umbrella of the `Apache Software Foundation + `_. + + Cassandra's data model has neither a logical structure nor a schema. For + the modeling it is recommended *«First write your queries then model + your data»*. Then usually a *Column Family* is created for each expected + request. The data is denormalised, but each column family responds to a + specific type of query. + + In Cassandra, the consistency can be specified for each request. This + allows specific requests to be very consistent while others sacrifice + consistency for speed. There are, for example, the following four levels + for write consistency: ANY - gewährleistet, dass die Daten in mindestens einem Knoten gespeichert - sind. + ensures that the data is stored in at least one node. ONE - gewährleistet, dass die Daten im Commit-Log von mindestens einer - Replica gespeichert sind. + ensures that the data is stored in the commit log of at least one + replica. QUORUM - gewährleistet, dass die Daten in einen Quorum von Replicas - gespeichert sind. + ensures that the data is stored in a quorum of replicas. ALL - gewährleistet, dass die Daten auf alle Replicas gespeichert sind. + ensures that the data is saved on all replicas. - Cassandra stellt zwei verschiedene APIs zur Verfügung: `Thrift - `_ und `CQL (Cassandra Query Language) + Cassandra provides two different APIs: `Thrift + `_ and `CQL (Cassandra Query Language) `_. Column Family - Column Families entsprechen Tabellen in relationalen Datenbanken. Sie - gruppieren Spalten gleichen oder ähnlichen Inhalts, z.B.: + Column families correspond to tables in relational databases. They group + columns with the same or similar content, e.g. .. code-block:: javascript @@ -116,196 +110,186 @@ Glossar } } + Consistent hash function + Consistent hash functions minimise the number of reallocations, since + not all keys have to be reallocated when a change occurs, only the size + of a hash table is changed. + + Consistency + The state of a database is said to be consistent if the stored data + meets all requirements for :term:`Semantic integrity`. + CouchDB - CouchDB ein Akronym für **C**\luster **o**\f **u**\nreliable - **c**\ommodity **h**\ardware **D**\ata **B**\ase. Dabei handelt es sich - um ein :doc:`nosql/document-oriented-db`. + CouchDB an acronym for **C**\luster **o**\f **u**\nreliable + **c**\ommodity **h**\ardware **D**\ata **B**\ase. This is a + :doc:`nosql/document-oriented-db`. Eventual Consistency - *»Konsistenz als Zustandsübergang, der irgendwann erreicht wird.«* + *«Consistency as a state transition that is reached at some point.»* - Der Begriff wurde für :term:`BASE` als Alternative zu :term:`ACID` - entwickelt. + The term was developed for :term:`BASE` as an alternative to + :term:`ACID`. Graph traversal - Graph traversal wird meist zur Suche von Knoten verwendet. Es gibt - verschiedene Algorithmen für solche Suchanfragen in einem Graphen, die - sich grob einteilen lassen in + Graph traversal is mostly used to find nodes. There are different + algorithms for such search queries in a graph, which can be roughly + divided into - * Breiten- und Tiefensuche (engl: breadth-first search, BFS und - depth-first search, DFS) + * Breadth-first search, BFS and depth-first search, DFS - Die Breitensuche beginnt mit allen Nachbarknoten des Startknotens. - Im nächsten Schritt werden dann die Nachbarn der Nachbarn durchsucht. - Die Pfadlänge erhöht sich mit jeder Iteration. + The breadth-first search begins with all neighboring nodes of the start node. + In the next step, the neighbors of the neighbors are then searched. The path + length increases with each iteration. - Die Tiefensuche verfolgt einen Pfad solange, bis ein Knoten ohne - ausgehende Kanten gefunden wird. Der Pfad wird anschließend - zurückverfolgt bis zu einem Knoten, der noch weitere ausgehende Kanten - hat. Dort wird die Suche dann fortgesetzt. + The depth-first search follows a path until a node with no outgoing edges is + found. The path is then traced back to a node that has further outgoing edges. + The search will then continue there. - * Algorithmische Traversierung + * Algorithmic traversal - Beispiele für die algorithmische Traversierung sind + Examples of algorithmic traversal are - * Hamiltonweg (Traveling Salesman) - * Eulerweg - * Dijkstra-Algorithmus + * Hamiltonian path (traveling salesman) + * Eulerian path + * Dijkstra’s algorithm - * Randomisierte Traversierung + * Randomised traversal - Der Graph wird nicht nach einem bestimmten Schema durchlaufen, sondern - der nächste Knoten wird zufällig ausgewählt. Dadurch kann vor allem bei - großen Graphen wesentlich schneller ein Suchergebnis präsentieren, dieses - ist jedoch nicht immer das beste. + The graph is not run through according to a certain scheme, but the next node + is selected at random. This allows a search result to be presented much + faster, especially with large graphs, but this is not always the best. - Graphenmodell - Ein Graph besteht aus einer Menge an Knoten und Kanten. Graphen werden - genutzt, um eine Vielfalt an Problemen durch Knoten, Kanten und ihren - Beziehungen darzustellen, z.B. in Navigationssystemen, in denen die Wege - in Form von Graphen gespeichert werden. + Graph model + A graph consists of a number of nodes and edges. Graphs are used to + represent a variety of problems through nodes, edges and their + relationships, for example in navigation systems in which the paths are + stored in the form of graphs. - Graphpartitionierung - Mit Graphpartitionierung werden Graphen in kleinere Teilgraphen - unterteilt. Dabei gibt es jedoch keine mathematisch exakte Methode, um - die Anzahl der durchschnittenen Kanten zu minimieren, sondern nur ein - paar heuristische Algorithmen, z.B. Clustering-Algorithmen, die stark - vernetzte Teilgraphen zu abstrakten Knoten zusammenziehen. + Graph partitioning + With graph partitioning, graphs are divided into smaller subgraphs. + However, there is no mathematically exact method to minimise the number + of intersected edges, but only a few heuristic algorithms, e.g. + clustering algorithms, which combine strongly networked subgraphs to + abstract nodes. - Von sich überlappenden Partitionierung spricht man bei Graphen, die - nicht komplett geteilt werden können und in mehreren Teilgraphen - existieren. + One speaks of overlapping partitioning in the case of graphs that cannot + be completely divided and exist in several subgraphs. HBase - HBase ist ein :doc:`nosql/column-oriented-db`, welches auf verteilten - Dateisystemen aufbaut und für real-time-Zugriffe auf großen - Datenbeständen konzipiert ist. + HBase is a :doc:`nosql/column-oriented-db`, which is based on + distributed file systems and is designed for real-time access to large + databases. Hypertable - Hypertable ist ein :doc:`nosql/column-oriented-db` und auf - verteilten Dateisystemen basiert. Das Datenmodell ist das einer - mehrdimensionalen Tabelle, die mit Schlüsseln durchsucht werden - kann. Die erste Dimension ist der sog. *row-key*, die zweite die - :term:`Column Family` die dritte Dimension der *Column Qualifier* - und die vierte Dimension die Zeit. - - Konsistente Hashfunktion - Konsistente Hashfunktionen minimieren die Anzahl der Neuzuordnungen, da - bei einer Änderung nicht alle Schlüssel neu zugeordnet werden müssen - sondern nur die Größe einer Hash-Tabelle geändert wird. - - Konsistenz - Der Zustand einer Datenbank wird als konsistent bezeichnet, wenn die - gespeicherten Daten alle Anforderungen for :term:`Semantische - Integrität` erfüllen. + Hypertable is a :doc:`nosql/column-oriented-db` and is based on + distributed file systems. The data model is that of a multi-dimensional + table that can be searched using keys. The first dimension is the + so-called *row key*, the second is the :term:`Column family`, the third + dimension is the *column qualifier* and the fourth dimension is time. + + Key/value pair + A value is always assigned to a specific key, which can consist of a + structured or arbitrary character string. These keys can be divided into + namespaces and databases. In addition to strings, the values can also + contain lists, sets or hashes. Locking - Als Locking bezeichnet man das Sperren von Daten für nebenläufige - Transaktionen. - - Je nach Art des Zugriffs gibt es unterschiedliche Lock-Verfahren: - - Optimistic Concurrency - Optimistic Concurrency, auch Optimistisches Locking geht davon aus, - dass wenige schreibende Zugriffe auf der Datenbank stattfinden und - lesende Zugriffe keine Sperre auslösen. Bei Änderungen wird dann - zunächst geprüft, ob der Zeitstempel seit dem Lesen der Daten - unverändert geblieben ist. - Pessimistic Locking - Pessimistic Locking geht von vielen Schreibzugriffen auf die - Datenbank aus. Daher sperren auch lesende Zugriffe die Daten werden - erst wieder freigegeben, wenn die Änderungen gespeichert sind. + Locking is the term used to describe the blocking of data for concurrent + transactions. + + There are different lock procedures, depending on the type of access: + + Optimistic concurrency + Optimistic concurrency, also called optimistic locking, assumes that + there are few write accesses to the database and read accesses do + not trigger a lock. In the event of changes, a check is first made + to determine whether the time stamp has remained unchanged since the + data was read. + Pessimistic locking + Pessimistic locking assumes a lot of write accesses to the database. + Read access is therefore also blocked. The data is only released + again when the changes have been saved. Two-phase locking (2PL) - Das Zwei-Phasen-Sperrprotokoll unterscheidet zwei Phasen von - Transaktionen: + The two-phase locking protocol distinguishes between two phases of + transactions: - #. Die Wachstumsphase, in welcher Sperren nur gesetzt, aber nicht - freigegeben werden dürfen. - #. Die Schrumpfungsphase, in welcher Sperren nur freigegeben, aber - nicht angefordert werden dürfen. + #. The growth phase in which locks can only be set but not released. + #. The shrinkage phase, in which locks can only be released but not + requested. - Das Zwei-Phasen-Sperrprotokoll kennt dabei drei Sperrzustände: + The two-phase lock protocol knows three lock states: - SLOCK, Shared Lock oder Read-Lock - wird bei lesendem Zugriff auf Daten gesetzt - XLOCK, Exclusive Lock oder Write-Lock - wird bei schreibendem Zugriff auf Daten gesetzt + SLOCK, shared lock or read lock + is set with read access to data + XLOCK, exclusive lock or write lock + is set with write access to data UNLOCK - hebt die Sperren SLOCK und XLOCK auf. + removes the locks SLOCK and XLOCK. MapReduce - MapReduce ist ein von Google Inc. 2004 eingeführtes Framework, das für - die nebenläufige Berechnungen enorm großer Datenmengen auf - Computerclustern verwendet wird. Es wurde durch die, in der funktionalen - Programmierung häufig verwendeten Funktionen *map* und *reduce* - inspiriert auch wenn die Semantik von diesen etwas abweicht. + MapReduce is a framework introduced by Google Inc. in 2004, which is + used for the concurrent computations of enormous amounts of data on + computer clusters. It was inspired by the *map* and *reduce* functions, + which are often used in functional programming, even if the semantics + deviate slightly from them. MongoDB - MongoDB ist eine schemafrei :doc:`nosql/document-oriented-db`, - die Dokumente im `BSON `_-Format verwaltet. + MongoDB is a schema-free :doc:`nosql/document-oriented-db`, + that manages documents in `BSON `_ format. MVCC – Multiversion Concurrency Control - MVCC werden kontrolliert konkurrierende Zugriffe auf Datensätze (Lesen, - Einfügen, Ändern, Löschen) durch verschiedene, unveränderliche Versionen - dieser Datensätze. Die verschiedenen Versionen werden in eine zeitliche - Reihenfolge gebracht, indem jede Version auf ihre Vorgängerversion - verweist. MVCC hat sich gerade bei :doc:`nosql/index` zu einer zentralen - Basistechnologie entwickelt, die es ermöglicht, konkurrierende Zugriffe - auch ohne das :term:`Locking` von Datensätzen zu koordinieren. + MVCC controls concurrent accesses to data records (read, insert, change, + delete) by different, unchangeable versions of these data records. The + various versions are arranged in a chronological order, with each + version referring to its previous version. MVCC has developed into a + central basic technology for NoSQL databases in particular, which makes + it possible to coordinate competing accesses even without locking data + records. Paxos - Paxos ist eine Familie von Protokollen zur Herstellung von Konsens in - einem Netzwerk unzuverlässiger oder fehlbarer Prozessoren. + Paxos is a family of protocols for building consensus on a network of + unreliable or fallible processors. - Property-Graph-Modell (PGM) - Knoten und Kanten bestehen aus Objekten mit darin eingebetteten - Eigenschaften (Properties). Es wird nicht nur ein Wert (Label) in einer - Kante bzw. einem Knoten gespeichert, sondern ein - :term:`Schlüssel/Wert-Paar`. + Property graph model (PGM) + Nodes and edges consist of objects with properties embedded in them. Not + only a value (label) is stored in an edge or a node, but a + :term:`Key/value pair`. Riak - Im Wesentlichen ist Riak ein dezentraler :term:`Schlüssel/Wert-Paar` mit - einer flexiblen :term:`MapReduce`-Engine. + In essence, Riak is a decentralised :term:`Key/value pair` with a + flexible :term:`MapReduce` engine. Redis - Redis ist ein :doc:`nosql/key-value-store`, die üblicherweise alle - Daten im RAM speichert. - - Schlüssel/Wert-Paar - Ein Wert ist immer einem bestimmten Schlüssel zugeordnet, der aus einer - strukturierten oder willkürlichen Zeichenkette bestehen kann. Diese - Schlüssel können in Namensräume und Datenbanken aufgeteilt werden. Die - Werte können neben Strings auch Listen, Sets oder Hashes enthalten. - - Semantische Integrität - Semantische Integrität ist immer dann gegeben, wenn die Eingaben richtig - und in sich stimmig sind. Dann wird auch von konsistenten Daten - gesprochen. Ist dies nicht der Fall, sind die Daten inkonsistent. In SQL - kann die semantische Integrität mit ``TRIGGER`` und ``CONSTRAINT`` - überprüft werden. - - Vektoruhr - Eine Vektoruhr ist eine Softwarekomponente zum Zuweisen von eindeutigen - Zeitstempeln an Nachrichten. Sie erlaubt, den Ereignissen in verteilten - Systemen aufgrund eines Zeitstempels eine Kausalordnung zuzuweisen und - insbesondere die Nebenläufigkeit von Ereignissen zu ermitteln. + Redis is a :doc:`nosql/key-value-store`, that usually stores all data in + RAM. + + Semantic integrity + Semantic integrity is always given when the entries are correct and + consistent. Then we talk of consistent data. If this is not the case, + the data is inconsistent. In SQL, the semantic integrity can be checked + with ``TRIGGER`` and ``CONSTRAINT`` + + Vector clock + A vector clock is a software component used to assign unique time stamps + to messages. It allows a causal order to be assigned to the events in + distributed systems on the basis of a time stamp and, in particular, to + determine the concurrency of events. XPATH - XPATH verarbeitet die Baumstruktur eines XML-Dokuments und erzeugt dabei - Ausschnitte aus XML-Dokumenten. Um als Ergebnis vollständige - XML-Dokumente zu erhalten, müssen diese z.B. mit :term:`XQuery` oder - :term:`XSLT` erstellt werden. XPATH ist keine vollständige - Abfragesprache, da sie auf Selektionen und Extraktionen beschränkt - ist. + XPATH processes the tree structure of an XML document and generates + extracts from XML documents. In order to receive complete XML documents + as a result, these must be created with :term:`XQuery` or :term:`XSLT`, + for example. XPATH is not a complete query language as it is limited to + selections and extractions. - XPATH ist ein Bestandteil von :term:`XQuery` seit Version 1.1 und ab - Version 2.0 wird XPATH durch :term:`XQuery` erweitert. + XPATH has been part of :term:`XQuery` since version 1.1 and from version + 2.0 onwards, XPATH is extended by :term:`XQuery`. XQuery - XQuery steht für *XML Query Language* und ist hauptsächlich eine - funktionale Sprache, bei der während einer Abfrage auch verschachtelte - Ausdrücke ausgewertet werden können. + XQuery stands for *XML Query Language* and is mainly a functional + language in which nested expressions can also be evaluated during a + query. XSLT - XSLT ist ein Akronym für **E**\xtensible **S**\tylesheet **L**\anguage - **T**\ransformation. Mit ihr lassen sich XML-Dokumente transformieren. + XSLT is an acronym for **E**\xtensible **S**\tylesheet **L**\anguage + **T**\ransformation. It can be used to transform XML documents. diff --git a/docs/data-rw/index.rst b/docs/data-rw/index.rst index dc814a6f..5e8286e6 100644 --- a/docs/data-rw/index.rst +++ b/docs/data-rw/index.rst @@ -1,13 +1,13 @@ -Daten lesen und schreiben -========================= +Read and write data +=================== -Einen Überblick über öffentliche Repositories mit Forschungsdaten erhaltet ihr -z.B. in der `Registry of research data repositories (re3data) -`_. +You can get an overview of public repositories with research data e.g. in the +`Registry of research data repositories (re3data) `_. -Neben spezifischen Python-Bibliotheken zum Zugriff auf :ref:`entfernte -Speichermedien ` und -:ref:`/data-rw/overview.rst#geodaten` stellen wir Euch vier Werkzeuge genauer vor: +In addition to specific Python libraries for accessing :ref:`remote storage +media` and +:ref:`/data-rw/overview.rst#geodata`, we will introduce you to four tools in +more detail: * :doc:`requests/index` * :doc:`beautifulsoup` @@ -16,20 +16,19 @@ Speichermedien ` und .. seealso:: `Scrapy `_ - Framework zum Extrahieren von Daten aus Websites als JSON-, CSV- oder - XML-Dateien. + Framework for extracting data from websites as JSON, CSV or XML files. `Pattern `_ - Python-Modul zum Data Mining, Verarbeitung natürlicher Sprache, ML und - Netzwerkanalyse + Python module for data mining, natural language processing, ML and + network analysis. `Web Scraping Reference `_ - Übersicht zu Web Scraping mit Python + Overview of web scraping with Python. -Zum Speichern von relationalen Daten, Python-Objekten und Geodaten stellen wir -Euch :doc:`postgresql/index`, :doc:`postgresql/sqlalchemy` und -:doc:`postgresql/postgis/index` vor. +We introduce :doc:`postgresql/index`, :doc:`postgresql/sqlalchemy` and +:doc:`postgresql/postgis/index` for storing relational data, Python objects and +geodata. -Zum Bereinigen und Vorbereiten der Daten stellen wir Euch einige Best Practices -und hilfreiche Python-Pakete in :doc:`../clean-prep/index` vor. +To clean up and prepare the data, we present you some best practices and helpful +Python packages in Data :doc:`../clean-prep/index`. .. toctree:: :hidden: diff --git a/docs/data-rw/intake/data-engineers.ipynb b/docs/data-rw/intake/data-engineers.ipynb index 73408d32..fb94f698 100644 --- a/docs/data-rw/intake/data-engineers.ipynb +++ b/docs/data-rw/intake/data-engineers.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Intake für Dateningenieure\n", + "# Intake for data engineers\n", "\n", - "Intake unterstützt Dateningenieure beim Bereitstellen von Daten und bei der Spezifikation der Datenquellen, der Verteilung der Daten, der Parametrisierung der Benutzeroptionen etc. Dies erleichtert Datenwissenschaftlern anschließend das einfache Erschließen zu den Daten, da die möglichen Optionen bereits im Katalog angegeben sind." + "Intake supports data engineers with the provision of data and with the specification of the data sources, the distribution of the data, the parameterisation of the user options etc. This makes it easier for data scientists to access the data afterwards, as the possible options are already specified in the catalog." ] }, { @@ -2765,7 +2765,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Intake-Datensätze werden mit sog. Treibern geladen, von denen einige schon mit dem Intake-Paket mitkommen, andere jedoch als [Plugin](https://intake.readthedocs.io/en/latest/plugin-directory.html) nachgeladen werden müssen. Die verfügbaren Treiber könnt ihr euch folgendermaßen anzeigen lassen:" + "Intake data sets are loaded with so-called drivers, some come with the intake package, but others have to be reloaded as [plug-ins](https://intake.readthedocs.io/en/latest/plugin-directory.html). You can display the available drivers as follows:" ] }, { @@ -2799,9 +2799,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Jedem dieser Treiber ist eine `intake.open_*`-Funktion zugeordnet. Es ist auch möglich, auf Treiber mit dem vollständig qualifizierten Namen (z.B. `package.submodule.DriverClass`) zu verweisen. Im folgenden Beispiel konzentrieren wir uns jedoch auf den `csv`-Treiber, der in der Standard-Intake-Installation enthalten ist.\n", + "Each of these drivers is assigned an `intake.open_*` function. It is also possible to refer to drivers by the fully qualified name (e.g. `package.submodule.DriverClass`). In the following example, however, we will focus on the csv driver that is included in the standard Intake installation.\n", "\n", - "Im Allgemeinen besteht der erste Schritt zum Schreiben eines Katalogeintrags darin, die entsprechende `open_*` Funktion zum Erstellen eines DataSource-Objekts zu verwenden:" + "In general, the first step in writing a catalog entry is to use the appropriate `open_*` function to create a DataSource object:" ] }, { @@ -2818,7 +2818,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die obige Angabe hat nun ein DataSource-Objekt erstellt, aber noch nicht überprüft, ob tatsächlich auf die Daten zugegriffen werden kann. Um zu testen, ob das Laden wirklich erfolgreich war, kann die Quelle selbst erschlossen (`source.discover`) oder gelesen (`source.read`) werden:" + "The above specification has now created a DataSource object, but has not yet checked whether the data can actually be accessed. To test whether the loading was really successful, the source itself can be opened (`source.discover`) or read (`source.read`):" ] }, { @@ -2934,7 +2934,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Nachdem wir festgestellt haben, das sich die Daten wie gewünscht laden lassen, wollen wir uns die Daten visuell erschließen:" + "After we have determined that the data can be loaded as desired, we want to open up the data visually:" ] }, { @@ -3060,7 +3060,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir können nun eine Quelle korrekt laden und erhalten auch eine grafische Ausgabe zur Erschließung der Daten. Dieses Rezept können wir uns nun in der YAML-Syntax ausgeben lassen mit:" + "Now we can load a source correctly and also receive a graphic output for opening up the data. We can now display this recipe in the YAML syntax with:" ] }, { @@ -3091,7 +3091,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Schließlich können wir eine YAML-Datei erstellen, die dieses Rezept mit einer zusätzlichen Beschreibung und dem getesteten Diagramm enthält:" + "Finally, we can create a YAML file containing this recipe with an additional description and the tested diagram:" ] }, { @@ -3129,7 +3129,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Um zu überprüfen, ob die YAML-Datei auch funktioniert, können wir sie erneut laden und versuchen, damit zu arbeiten:" + "To check that the YAML file works too, we can reload it and try to work with it:" ] }, { @@ -3263,7 +3263,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der Katalog scheint funktionsfähig und kann nun freigegeben werden. Der einfachste Weg, einen Intake-Katalog freizugeben, besteht darin, ihn an einem Ort abzulegen, an dem er von Ihrer Zielgruppe gelesen werden kann. In diesem Tutorial, das in einem Git-Repo gespeichert ist, kann dies die URL der Datei im Repo sein. Alles, was ihr für eure Benutzer freigeben müsst, ist die URL des Katalogs. Ihr könnt dies selbst ausprobieren mit:" + "The catalog appears to be functional and can now be released. The easiest way to share an Intake catalog is to put it in a place where it can be read by your target audience. In this tutorial stored in a Git repo, this can be the url of the file in the repo. All you have to share with your users is the URL of the catalog. You can try this yourself with:" ] }, { @@ -3366,9 +3366,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> ## Hinweis:\n", + "> ## Note:\n", "> \n", - "> Dieser Katalog ist auch wieder eine DataSource-Instanz, d.h., dass ihr aus anderen Katalogen darauf verweisen und so eine Hierarchie von Datenquellen aufbauen könnt. Beispielsweise verfügt ihr über einen Stamm- oder Hauptkatalog, der auf mehrere andere Kataloge verweist, die jeweils Einträge eines bestimmten Typs enthalten. und das Ganze kann z.B. mit [Intake-GUI](https://jupyter-tutorial.readthedocs.io/de/latest/gather/intake/gui.html) durchsucht werden. Auf diese Weise hat die Datenerfassung insgesamt eine Struktur, die das Navigieren zum richtigen Datensatz vereinfacht. Ihr könnt sogar separate Hierarchien haben, die auf dieselben Daten verweisen." + "> This catalog is also a DataSource instance, i.e. you can refer to it from other catalogs and thus build a hierarchy of data sources. For example, you have a master or main catalog that references several other catalogs, each with entries of a certain type and the whole thing can e.g. be searched with [Intake-GUI](gui.ipynb). In this way, the overall data acquisition structure has a structure that makes it easier to navigate to the correct data set. You can even have separate hierarchies that reference the same data." ] }, { diff --git a/docs/data-rw/intake/data-scientists.ipynb b/docs/data-rw/intake/data-scientists.ipynb index d82d7341..87473609 100644 --- a/docs/data-rw/intake/data-scientists.ipynb +++ b/docs/data-rw/intake/data-scientists.ipynb @@ -4,18 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Intake für Datenwissenschaftler\n", + "# Intake for data scientists\n", "\n", - "Intake erleichtert das Laden vieler verschiedener Formate und Typen. Um einen vollständigen Überblick zu erhalten, schaut euch das [Plugin Directory](https://intake.readthedocs.io/en/latest/plugin-directory.html) und das [Intake Project Dashboard](https://intake.github.io/status/) an. Intake überführt die Daten dann in übliche Speicherformate wie Pandas DataFrames, Numpy-Arrays oder Python-Listen. Anschließend sind sie leicht durchsuchbar und auch für verteilte Systeme zugänglich. Sollte euch ein Plugin fehlen, könnt ihr auch selbst welche estellen, wie in [Making Drivers](https://intake.readthedocs.io/en/latest/making-plugins.html) beschrieben." + "Intake makes it easy to load many different formats and types. For a complete overview, take a look at the [Plugin Directory](https://intake.readthedocs.io/en/latest/plugin-directory.html) and the [Intake Project Dashboard](https://intake.github.io/status/). Intake then transfers the data to common storage formats such as Pandas DataFrames, Numpy arrays or Python lists. They are then easily searchable and also accessible to distributed systems. If you are missing a plugin, you can also order one yourself, as described in [Making Drivers](https://intake.readthedocs.io/en/latest/making-plugins.html)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Laden einer Datenquelle\n", + "## Load a data source\n", "\n", - "Im Folgenden werden wir zwei csv-Datensätze lesen und in einen Intake-Katalog überführen. " + "Hereinafter we will read two csv data records and transfer them to an intake catalog." ] }, { @@ -48,24 +48,24 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Konfigurieren des Suchpfades für Datenquellen\n", + "### Configure the search path for data sources\n", "\n", - "Intake überprüft die Intake-Konfigurationsdatei nach `catalog_pat`und die Umgebungsvariable `\"INTAKE_PATH\"` auf eine durch Doppelpunkte getrennte Liste von Pfaden bzw. Semikolon in Windows, um nach Katalogdateien zu suchen. Beim Import `intake` werden alle Einträge aus allen Katalogen angezeigt, auf die als Teil eines globalen Katalogs von `intake.cat` referenziert werden." + "Intake checks the Intake configuration file for `catalog_path` and the environment variable `\"INTAKE_PATH\"` for a colon-separated list of paths or semicolons in Windows to look for catalog files. When importing `intake`, all entries from all catalogs that are referenced by `intake.cat` as part of a global catalog are displayed." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Daten lesen\n", + "## Read data\n", "\n", - "Intake liest Daten in Container verschiedener Formate:\n", + "Intake reads data in containers of various formats:\n", "\n", - "* Tabellen in Pandas DataFrames\n", - "* Mehrdimensionale Array in Numpy Arrays\n", - "* Semistrukturierte Daten in Python-Listen von Objekten, üblicherweise Dictionaries\n", + "* Tables in Pandas DataFrames\n", + "* Multi-dimensional arrays in numpy arrays\n", + "* Semi-structured data in Python lists of objects, usually dictionaries\n", "\n", - "Um herauszufinden, in welchem Containerformat Intake die Daten vorhält, könnt ihr das `container`-Attribut verwenden:" + "To find out in which container format Intake holds the data, you can use the `container` attribute:" ] }, { @@ -92,7 +92,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Neben `dataframe` kann das Ergebnis auch `ndarray` oder `python` sein." + "In addition to `dataframe`, the result can also be `ndarray` or `python`." ] }, { diff --git a/docs/data-rw/intake/gui.ipynb b/docs/data-rw/intake/gui.ipynb index bc29f0ce..acb39f40 100644 --- a/docs/data-rw/intake/gui.ipynb +++ b/docs/data-rw/intake/gui.ipynb @@ -4,17 +4,17 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Intake-GUI : Erkunden von Daten in einer grafischen Oberfläche\n", + "# Intake-GUI: Exploring data in a graphical user interface\n", "\n", - "Intake-GUI wurde neu implementiert, sodass sie nicht nur in Jupyter-Notebooks, sondern auch in anderen Webanwendungen bereitgestellt werden kann. Er zeigt den Inhalt aller installierten Kataloge an und ermöglicht die Auswahl lokaler und entfernter Kataloge sowie das Durchsuchen und Auswählen von Einträgen aus diesen.\n", + "Intake GUI has been re-implemented so that it can be made available not only in Jupyter notebooks, but also in other web applications. It displays the contents of all installed catalogs and enables local and remote catalogs to be selected and to be searched and selected from.\n", "\n", - "Intake unterstützt die Arbeitsteilung zwischen Daten-Ingenieuren, die Daten kuratieren, verwaltet und verbreitet, und Daten-Wissenschaftlern, die Daten analysieren und visualisieren ohne wissen zu müssen, wie sie gespeichert sind.\n", + "Intake supports the division of labor between data engineers who curate, manage, and deploy data, and data scientists who analyse and visualise data without having to know how it’s stored.\n", "\n", - "Das Intake-GUI basiert auf [Panel](https://jupyter-tutorial.readthedocs.io/de/latest/web/dashboards/panel/index.html) wobei das Bedienfeld eine zusammensetzbare Dashboard-Lösung für die Anzeige von Plots, Bildern, Tabellen, Texten sowie Widgets bietet. Panel funktioniert sowohl in einem Jupyter-Notebook als auch in einer eigenständigen Tornado-Anwendung.\n", + "The Intake GUI is based on [Panel](../../web/dashboards/panel/index.rst), with the control panel offering a composite dashboard solution for displaying plots, images, tables, texts and widgets. Panel works both in a Jupyter notebook and in a standalone Tornado application.\n", "\n", - "Aus Sicht des Dateningenieurs bedeutet dies, dass Sie die Aufnahme-GUI an einem Endpunkt bereitstellen und als Datenexplorationswerkzeug für Ihre Datenbenutzer verwenden können. Dies bedeutet auch, dass es einfach ist, die GUI anzupassen und neu zu organisieren, um Ihr eigenes Logo einzufügen, Teile davon in Ihren eigenen Anwendungen wiederzuverwenden oder neue Funktionen hinzuzufügen.\n", + "From a data engineer’s point of view, this means that you can deploy the recording GUI at an endpoint and use it as a data exploration tool for your data users. This also means that it’s easy to adapt and reorganise the GUI in order to insert your own logo, reuse parts of it in your own applications or add new functions.\n", "\n", - "Zukünftig soll Intake-GUI auch die Eingabe von Benutzerparametern erlauben sowie das Bearbeiten und Speichern von Katalogen." + "In the future, Intake-GUI should also allow the input of user parameters as well as the editing and saving of catalogs." ] }, { @@ -1530,22 +1530,22 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das GUI enthält drei Hauptbereiche:\n", + "The GUI contains three main areas:\n", "\n", - "1. eine Liste von Katalogen. Der standardmäßig angezeigte *builtin*-Katalog enthält im System installierte Datensätze, genau wie `intake.cat`.\n", - "2. eine Liste der Quellen im aktuell ausgewählten Katalog.\n", - "3. eine Beschreibung der aktuell ausgewählten Quelle." + "1. a list of catalogs. The *builtin* catalog shown by defaul tcontains data records installed in the system, just like `intake.cat`.\n", + "2. a list of the sources in the currently selected catalog.\n", + "3. a description of the currently selected source." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Ad 1: Kataloge\n", + "### Ad 1: Catalogs\n", "\n", - "Aktuell wird in der Liste der Kataloge kein Katalog angezeigt. Unter den drei Hauptbereichen befinden sich jedoch drei Schaltflächen, mit denen Kataloge hinzugefügt, entfernt oder durchsucht werden können. \n", + "No catalog is currently displayed in the list of catalogs. However, under the three main areas there are three buttons that can be used to add, remove, or search catalogs. \n", "\n", - "Die Schaltflächen sind auch über die API verfügbar, z.B. für *Add Catalog* mit:" + "The buttons are also available through the API, e.g. for Add Catalog with:" ] }, { @@ -1561,7 +1561,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Remote-Kataloge sind z.B. verfügbar unter\n", + "Remote catalogs are e.g. available under\n", "\n", "* https://s3.amazonaws.com/earth-data/UCMerced_LandUse/catalog.yml\n", "* https://raw.githubusercontent.com/ContinuumIO/anaconda-package-data/master/catalog/anaconda_package_data.yaml\n", @@ -1572,11 +1572,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Ad 2. Quellen\n", + "### Ad 2. Sources\n", "\n", - "Durch die Auswahl einer Quelle aus der Liste wird der Beschreibungstext auf der linken Seite der Benutzeroberfläche aktualisiert.\n", + "Selecting a source from the list updates the descriptive text on the left side of the user interface.\n", "\n", - "Auch dieser ist über die API verfügbar:" + "This is also available via the API:" ] }, { @@ -1622,7 +1622,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dieser besteht aus einer Liste regulärer Intake-Datenquelleinträge. Um uns die ersten Einträge anzuschauen, können wir folgendes eingeben:" + "This consists of a list of regular Intake data source entries. To look at the first entries, we can enter the following:" ] }, { @@ -5114,9 +5114,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Ad 3. Quellansicht\n", + "### Ad 3. Source view\n", "\n", - "Sobald Kataloge geladen sind und die gewünschten Quellen ausgewählt wurden, sind diese unter dem Attribut `intake.gui.sources` verfügbar. Jeder Quelleneintrag verfügt über Methoden und kann wie jeder Katalogeintrag als Datenquelle geöffnet werden. Für *Source: UCMerced_LandUse_by_landuse* sieht der Eintrag beispielsweise so aus:\n", + "As soon as catalogs are loaded and the desired sources have been selected, they are available under the attribute `intake.gui.sources`. Each source entry has methods and can be opened as a data source like any catalog entry. For *Source: UCMerced_LandUse_by_landuse*, the entry looks like this:\n", "\n", "```\n", "name: UCMerced_LandUse_by_landuse\n", @@ -5139,14 +5139,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Unter der Liste der Quellen befindet sich eine Reihe von Schaltflächen zum Erschließen der ausgewählten Datenquelle: Dabei öffnet **Plot** ein Unterfenster zum Anzeigen der vordefinierten (d.h. der in yaml angegebenen) Plots für die ausgewählte Quelle." + "Below the list of sources there is a series of buttons for opening up the selected data source: **Plot** opens a sub-window to display the predefined (i.e. the ones specified in yaml) plots for the selected source." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "> ## Siehe auch:\n", + "> ## See also:\n", "> \n", "> * [GUI](https://intake.readthedocs.io/en/latest/gui.html)" ] diff --git a/docs/data-rw/intake/index.rst b/docs/data-rw/intake/index.rst index a7a49a3a..49aaef57 100644 --- a/docs/data-rw/intake/index.rst +++ b/docs/data-rw/intake/index.rst @@ -1,9 +1,9 @@ Intake ====== -Intake erleichtert das Auffinden, Untersuchen, Laden und Verbreiten von Daten. -Es ist damit nicht nur für Datenwissenschaftler und -ingenieure interessant, -sondern auch für Datenanbieter. +Intake makes it easy to find, explore, load, and distribute data. Therefore it +is not only interesting for data scientists and engineers, but also for data +providers. .. seealso:: * `Docs `_ diff --git a/docs/data-rw/intake/install.rst b/docs/data-rw/intake/install.rst index 022fa279..7474a630 100644 --- a/docs/data-rw/intake/install.rst +++ b/docs/data-rw/intake/install.rst @@ -1,26 +1,25 @@ -Intake installieren -=================== +Install Intake +============== -Anforderungen -------------- +Requirements +------------ -Für die Verwendung von `intake.gui` müssen aktuelle Versionen von -Bokeh≥2.0 und Panel verfügbar sein. +Current versions of Bokeh≥2.0 and Panel must be available in order to use +`intake.gui`. Installation ------------ -Intake lässt sich einfach für euren Jupyter-Kernel installieren mit: +Intake can be easily installed for your Jupyter kernel with: .. code-block:: console $ pipenv install intake -Katalog mit Beispieldaten erstellen ------------------------------------ +Create a catalog with sample data +--------------------------------- -Für die nachfolgenden Beispiele benötigen wir einige Datensätze, die wir -erstellen mit: +For the following examples we need some data sets that we create with: .. code-block:: console diff --git a/docs/data-rw/nosql/column-oriented-db.rst b/docs/data-rw/nosql/column-oriented-db.rst index c758c34f..cd0d4e13 100644 --- a/docs/data-rw/nosql/column-oriented-db.rst +++ b/docs/data-rw/nosql/column-oriented-db.rst @@ -1,16 +1,15 @@ -Spaltenorientierte Datenbanksysteme -=================================== +Column-oriented database systems +================================ -Spaltenorientierte Datenbanken, auch Wide Column Stores genannt, speichern Daten -mehrerer Einträge zusammen mit einem Zeitstempel in Spalten. Spalten mit -ähnlichen oder verwandten Inhalten können in einer :term:`Column Family` -zusammengefasst werden. +Column-oriented databases, also known as wide column stores, store data from +several entries together with a time stamp in columns. Columns with similar or +related content can be combined in a :term:`Column family`. -Datenbanksysteme +Database systems ---------------- -Beispiele für spaltenorientierte Datenbanksysteme sind -:term:`Cassandra`, :term:`Hypertable` und :term:`HBase`. +Examples of column-oriented database systems are :term:`Cassandra`, +:term:`Hypertable` and :term:`HBase`. +------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Home** | `Cassandra`_ | `Hypertable`_ | `HBase`_ | @@ -19,39 +18,36 @@ Beispiele für spaltenorientierte Datenbanksysteme sind +------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Docs** | `cassandra.apache.org/doc/`_ | `hypertable.com/documentation`_| `hbase.apache.org/book.html`_ | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anwendungsgebiete** | Georedundanz, hohe | Das Bigtable-Design von | IoT, fraud detection, | -| | Schreibgeschwindigkeit, | Hypertable löst horizontale | recommendation engines | -| | demokratische Peer-to-peer | Skalierungsprobleme durch ein | | -| | (P2P)-Architektur, Daten mit | verteiltes Speichersystem für | | -| | definierter Lebenszeit | strukturierte Daten. | | -| | | | | +| **Application areas** | Georedundancy, high writing | Hypertable's Bigtable design | IoT, fraud detection, | +| | speed, democratic peer-to-peer | solves horizontal scaling | recommendation engines | +| | (P2P) architecture, data with | problems through a distributed | | +| | a defined lifetime | storage system for structured | | +| | | data. | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Entwicklungssprache**| Java | C++ | Java | +| **Development | Java | C++ | Java | +| language** | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Lizenzen** | Apache License 2.0 | GPL-3.0 License | Apache-2.0 License | +| **Licenses** | Apache License 2.0 | GPL-3.0 License | Apache-2.0 License | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Datenmodell** | :term:`Column Family` | Zuordnungstabellen | In Regionen unterteilte | -| | entsprechen Tabellen, | (engl. Associative arrays) | Tabellen | -| | *Keyspaces* Datenbanken; keine | | | -| | logische Struktur, kein Schema | | | -| | | | | +| **Data model** | :term:`Column Family` | Associative arrays | Tables divided into regions | +| | correspond to tables, | | | +| | *Keyspaces* databases; no | | | +| | logical structure, no scheme | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Query-Langauge** | `Cassandra Query Language | `Hypertable Query Language | Java Client API, Thrift/REST | +| **Query langauge** | `Cassandra Query Language | `Hypertable Query Language | Java Client API, Thrift/REST | | | (CQL)`_ | (HQL)`_ | API | -| | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Transaktionen, | :term:`Eventual Consistency` | :term:`MVCC – Multiversion | :term:`ACID` je Zeile, | -| Nebenläufigkeit** | | Concurrency Control` | :term:`MVCC – Multiversion | +| **Transactions, | :term:`Eventual Consistency` | :term:`MVCC – Multiversion | :term:`ACID` per line, | +| concurrency** | | Concurrency Control` | :term:`MVCC – Multiversion | | | | | Concurrency Control` | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Replikation, | SimpleStrategy, | Replikation auf Dateisystem- | Master-Slave-Replikation | -| Skalierung** | NetworkTopologyStrategy und | Ebene | | +| **Replication, | SimpleStrategy, | File system level replication | Master-Slave-Replikation | +| skaling** | NetworkTopologyStrategy and | | | | | OldNetworkTopologyStrategy | | | -| | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anmerkungen** | | basiert auf verteilten | | -| | | Dateisystemen wie Apache | | -| | | Hadoop, DFS oder GlusterFS | | +| **Remarks** | | is based on distributed file | | +| | | systems such as Apache Hadoop, | | +| | | DFS or GlusterFS | | +------------------------+--------------------------------+--------------------------------+--------------------------------+ .. _`Cassandra`: https://cassandra.apache.org/ diff --git a/docs/data-rw/nosql/document-oriented-db.rst b/docs/data-rw/nosql/document-oriented-db.rst index bfe0a90c..084b03d1 100644 --- a/docs/data-rw/nosql/document-oriented-db.rst +++ b/docs/data-rw/nosql/document-oriented-db.rst @@ -1,16 +1,14 @@ -Dokumentenorientierte Datenbanksysteme -====================================== +Document-oriented database systems +================================== -Ein Dokument in diesem Zusammenhang ist eine strukturierte Zusammenstellung -bestimmter Daten. Die Daten eines Dokumente werden als -:term:`Schlüssel/Wert-Paar` gespeichert, wobei der Wert auch eine Liste oder ein -Array sein kann. +A document in this context is a structured compilation of certain data. The data +of a document is stored as a :term:`Key/value pair`, whereby the value can also +be a list or an array. -Datenbanksysteme +Database systems ---------------- - -Dokumentenorientierte Datenbanksysteme sind z.B. MongoDB, CouchDB, Riak, -OrientDB und ArangoDB. +Document-oriented database systems are, for example, MongoDB, CouchDB, Riak, +OrientDB and ArangoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Home** | `MongoDB`_ | `CouchDB`_ | `Riak`_ | `OrientDB`_ | `ArangoDB`_ | @@ -19,34 +17,35 @@ OrientDB und ArangoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Docs** | `docs.mongodb.com`_ | `docs.couchdb.org`_ | `docs.riak.com`_ | `www.orientdb.com/docs`_ | `arangodb.com/documentation/`_ | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anwendungsgebiete** | IoT, Mobile apps, CMS, | Mobile, CRM, CMS, … | Session storage, Log data, | Stammdatenverwaltung, soziale | Fraud Detection, IoT, | -| | `einfache Geodaten`_, … | | Sensor data, CMS | Netzwerke, `Time Series`_, | Identitätsmanagement, | -| | | | | `Key Value`_, `Chat`_, | E-Commerce, Netzwerk, Logistik,| -| | | | | Verkehrsmanagement | CMS | +| **Application areas** | IoT, Mobile apps, CMS, | Mobile, CRM, CMS, … | Session storage, Log data, | Master data management, social | Fraud Detection, IoT, | +| | `simple geospatial data`_, … | | Sensor data, CMS | networks, `Time Series`_, | identity management, | +| | | | | `Key Value`_, `Chat`_, | e-commerce, network, logistics,| +| | | | | traffic management | CMS | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Entwicklungssprache**| C++ | Erlang | Erlang | Java | C++, JavaScript | +| **Development | C++ | Erlang | Erlang | Java | C++, JavaScript | +| language** | | | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Lizenzen** | Server Side Public License | Apache License 2.0 | Apache License 2.0 | Apache License 2.0 | Apache License 2.0 | +| **Licenses** | Server Side Public License | Apache License 2.0 | Apache License 2.0 | Apache License 2.0 | Apache License 2.0 | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Datenmodell** | Flexibles Schema mit | Flexibles Schema | Im Wesentlichen | Multi-Model | Multi-Model: Dokumente, Graphen| -| | denormalisiertem Modell | | :term:`Schlüssel/Wert-Paar` | | und :term:`Schlüssel/Wert-Paar`| +| **Data model** | Flexible scheme with | Flexible scheme | Essentially | Multi-Model | Multi-model: documents, graphs | +| | denormalised model | | :term:`Key/Value pair` | | and :term:`Key/value pair` | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Query-Langauge** | jQuery, :term:`MapReduce` | REST, :term:`MapReduce` | Keyfilter, :term:`MapReduce`, | `Extended SQL`_, `Gremlin`_ |`ArangoDB Query Language (AQL)`_| -| | | | Link-Walking, keine Ad-hoc | | | -| | | | Queries möglich | | | +| **Query langauge** | jQuery, :term:`MapReduce` | REST, :term:`MapReduce` | Key filter, :term:`MapReduce`, | `Extended SQL`_, `Gremlin`_ |`ArangoDB Query Language (AQL)`_| +| | | | link walking, no ad-hoc | | | +| | | | queries possible | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Transaktionen, | :term:`Two-phase locking (2PL)`| * :term:`Two-phase locking | :term:`ACID` | :term:`ACID` | :term:`ACID`, | -| Nebenläufigkeit** | | (2PL)`, | | | :term:`MVCC – Multiversion | -| | | * einzelner Server: | | | Concurrency Control` | -| | | :term:`ACID`, | | | | -| | | * verteilte Systeme: | | | | -| | | :term:`BASE` | | | | +| **Transactions, | :term:`Two-phase locking (2PL)`|* :term:`Two-phase locking (2PL)| :term:`ACID` | :term:`ACID` | :term:`ACID`, | +| concurrency** | | (2PL)`, | | | :term:`MVCC – Multiversion | +| | |* single server: | | | Concurrency Control` | +| | | :term:`ACID`, | | | | +| | |* distributed systems: | | | | +| | | :term:`BASE` | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Replikation, | Master-Slave-Replikation, | Master-Master-Replikation | Multi-Master-Replikation | Multi-Master-Replikation, | Master-Slave-Replikation, | -| Skalierung** | Auto-Sharding | | | Sharding | Sharding | +| **Replication, | Master-Slave replikation, | Master-master replication | Multi-master replication | Multi-Master-Replikation, | Master-slave replication, | +| skaling** | Auto-Sharding | | | Sharding | sharding | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anmerkungen** | `BSON` mit einre maximalen | | | | | -| | Dokumentengröße von 16 MB. | | | | | +| **Remarks** | `BSON` with a maximum | | | | | +| | document size of 16 MB. | | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ .. _`MongoDB`: https://www.mongodb.com/ @@ -70,5 +69,5 @@ OrientDB und ArangoDB. .. _`Extended SQL`: https://orientdb.org/docs/2.2.x/SQL.html .. _`Gremlin`: https://github.com/tinkerpop/gremlin/wiki .. _`ArangoDB Query Language (AQL)`: https://www.arangodb.com/docs/stable/aql/ -.. _`einfache Geodaten`: https://docs.mongodb.com/manual/core/geospatial-indexes/ +.. _`simple geospatial data`: https://docs.mongodb.com/manual/core/geospatial-indexes/ .. _`BSON`: http://www.bsonspec.org/ diff --git a/docs/data-rw/nosql/graph-db.rst b/docs/data-rw/nosql/graph-db.rst index 7332ac11..ec00517b 100644 --- a/docs/data-rw/nosql/graph-db.rst +++ b/docs/data-rw/nosql/graph-db.rst @@ -1,55 +1,50 @@ -Graphdatenbanksysteme -===================== +Graph database systems +====================== -Graphdatenbanken sind spezialisiert auf vernetzte Informationen und -möglichst einfache und effiziente :term:`Graph traversal`. +Graph databases specialise in networked information and the simplest and most +efficient possible :term:`Graph traversal`. -Graphenmodell -------------- +Graph model +----------- -Ein Graph besteht aus einer Menge an Knoten und Kanten. Graphen werden genutzt, -um eine Vielfalt an Problemen durch Knoten, Kanten und ihren Beziehungen -darzustellen, z.B. in Navigationssystemen, in denen die Wege in Form von Graphen -gespeichert werden. +A graph consists of a number of nodes and edges. Graphs are used to represent a +variety of problems through nodes, edges and their relationships, for example +in navigation systems in which the paths are stored in the form of graphs. Graph traversal --------------- -Graph traversal wird meist zur Suche von Knoten verwendet. Es gibt verschiedene -Algorithmen für solche Suchanfragen in einem Graphen, die sich grob einteilen -lassen in +Graph traversal is mostly used to find nodes. There are different algorithms for +such search queries in a graph, which can be roughly divided into -* Breiten- und Tiefensuche (engl: breadth-first search, BFS und - depth-first search, DFS) +* Breadth-first search, BFS and depth-first search, DFS - Die Breitensuche beginnt mit allen Nachbarknoten des Startknotens. - Im nächsten Schritt werden dann die Nachbarn der Nachbarn durchsucht. - Die Pfadlänge erhöht sich mit jeder Iteration. + The breadth-first search begins with all neighboring nodes of the start node. + In the next step, the neighbors of the neighbors are then searched. The path + length increases with each iteration. - Die Tiefensuche verfolgt einen Pfad solange, bis ein Knoten ohne - ausgehende Kanten gefunden wird. Der Pfad wird anschließend - zurückverfolgt bis zu einem Knoten, der noch weitere ausgehende Kanten - hat. Dort wird die Suche dann fortgesetzt. + The depth-first search follows a path until a node with no outgoing edges is + found. The path is then traced back to a node that has further outgoing edges. + The search will then continue there. -* Algorithmische Traversierung +* Algorithmic traversal - Beispiele für die algorithmische Traversierung sind + Examples of algorithmic traversal are - * Hamiltonweg (Traveling Salesman) - * Eulerweg - * Dijkstra-Algorithmus + * Hamiltonian path (traveling salesman) + * Eulerian path + * Dijkstra’s algorithm -* Randomisierte Traversierung +* Randomised traversal - Der Graph wird nicht nach einem bestimmten Schema durchlaufen, sondern - der nächste Knoten wird zufällig ausgewählt. Dadurch kann vor allem bei - großen Graphen wesentlich schneller ein Suchergebnis präsentieren, dieses - ist jedoch nicht immer das beste. + The graph is not run through according to a certain scheme, but the next node + is selected at random. This allows a search result to be presented much + faster, especially with large graphs, but this is not always the best. -Datenbanksysteme +Database systems ---------------- -Typische Graphdatenbanken sind Neo4j, OrientDB InfiniteGraph und ArangoDB. +Typical graph databases are Neo4j, OrientDB InfiniteGraph and ArangoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Home** | `Neo4j`_ | `OrientDB`_ | `InfiniteGraph`_ | `ArangoDB`_ | @@ -58,41 +53,41 @@ Typische Graphdatenbanken sind Neo4j, OrientDB InfiniteGraph und ArangoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Docs** | `neo4j.com/docs/`_ | `orientdb.org/docs/`_ | `InfiniteGraph Tutorials`_ | `arangodb.com/documentation/`_ | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anwendungsgebiete** | CMS, Soziale Netzwerke, | Stammdatenverwaltung, soziale | Erweiterung von | Fraud Detection, IoT, | -| | GIS-Systeme, ERP, … | Netzwerke, `Time Series`_, | Objectivity/DB-Installationen | Identitätsmanagement, | -| | | `Key Value`_, | | E-Commerce, Netzwerk, Logistik,| -| | | Verkehrsmanagement | | CMS | +| **Application areas** | CMS, social networks, | Master data management, social | Extension of | Fraud Detection, IoT, | +| | GIS systems, ERP, … | networks, `time series`_, | Objectivity/DB installations | identity management,, | +| | | `key value`_, | | e-commerce, network, logistics,| +| | | traffic management | | CMS | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Entwicklungssprache**| Java | Java | Java | C++, JavaScript | +| **Development | Java | Java | Java | C++, JavaScript | +| language** | | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Lizenzen** | AGPL u. kommerziell | Apache License 2.0 | kommerziell | Apache License 2.0 | +| **Licenses** | AGPL and commercially | Apache License 2.0 | commercially | Apache License 2.0 | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Datenmodell** | :term:`Property-Graph-Modell | Multi-Model | :term:`Property-Graph-Modell | Multi-Model: Dokumente, Graphen| -| | (PGM)` | | (PGM)` | und :term:`Schlüssel/Wert-Paar`| +| **Data model** | :term:`Property graph model | Multi-Model | :term:`Property graph model | Multi-model: documents, graphs | +| | (PGM)` | | (PGM)` | and :term:`Key/value pair` | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Query-Langauge** | REST, `Cypher`_, `Gremlin`_ | `Extended SQL`_, `Gremlin`_ | Traverser API, PQL |`ArangoDB Query Language (AQL)`_| +| **Query langauge** | REST, `Cypher`_, `Gremlin`_ | `Extended SQL`_, `Gremlin`_ | Traverser API, PQL |`ArangoDB Query Language (AQL)`_| +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Transaktionen, | * :term:`Two-phase locking | :term:`ACID` | :term:`ACID` | :term:`ACID`, | -| Nebenläufigkeit** | (2PL)`, | | | :term:`MVCC – Multiversion | -| | * einzelner Server: | | | Concurrency Control` | -| | :term:`ACID`, | | | | -| | * verteilte Systeme: | | | | -| | :term:`BASE` | | | | +| **Transactions, |* :term:`Two-phase locking(2PL)`| :term:`ACID` | :term:`ACID` | :term:`ACID`, | +| concurrency** | | | | :term:`MVCC – Multiversion | +| |* single Server: | | | Concurrency Control` | +| | :term:`ACID` | | | | +| |* distributed systems: | | | | +| | :term:`BASE` | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Replikation, | Master-Slave mit Master | Multi-Master-Replikation, | Objectivity/DB, | Master-Slave-Replikation, | -| Skalierung** | Failover | Sharding | keine | Sharding | -| | | | :term:`Graphpartitionierung` | | +| **Replication, | Master-slave with master | Multi-master replication, | Objectivity/DB, | Master-slave replication, | +| skaling** | failover | Sharding | no | sharding | +| | | | :term:`Graph partitioning` | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anmerkungen** | | | InfiniteGraph ist eine, auf | | -| | | | dem :doc:`object-db` | | -| | | | Objectivity/DB aufsetzende | | -| | | | Graphdatenbank, wobei die | | -| | | | Objekte durch Kanten verbunden | | -| | | | werden. Hierbei sind auch | | -| | | | mehrfache und bidirektionale | | -| | | | Kanten erlaubt. | | +| **Remarks** | | | InfiniteGraph is a graph | | +| | | | database on top of the | | +| | | | :doc:`object-db` | | +| | | | Objectivity/DB, whereby the | | +| | | | objects are connected by edges.| | +| | | | Multiple and bidirectional | | +| | | | edges are also allowed here. | | | | | | | | -| | | | Iteratoren entsprechen dem | | +| | | | Iterators correspond to the | | | | | | :term:`Graph traversal`. | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ @@ -103,8 +98,8 @@ Typische Graphdatenbanken sind Neo4j, OrientDB InfiniteGraph und ArangoDB. .. _`ArangoDB`: https://www.arangodb.com/ .. _`orientechnologies/orientdb`: https://github.com/orientechnologies/orientdb .. _`arangodb/arangodb`: https://github.com/arangodb/arangodb -.. _`Time Series`: https://orientdb.org/docs//2.0/orientdb.wiki/Time-series-use-case.html -.. _`Key Value`: https://orientdb.org/docs//2.0/orientdb.wiki/Key-Value-use-case.html +.. _`time series`: https://orientdb.org/docs//2.0/orientdb.wiki/Time-series-use-case.html +.. _`key value`: https://orientdb.org/docs//2.0/orientdb.wiki/Key-Value-use-case.html .. _`neo4j.com/docs/`: https://neo4j.com/docs/ .. _`orientdb.org/docs/`: https://orientdb.org/docs/ .. _`InfiniteGraph Tutorials`: diff --git a/docs/data-rw/nosql/index.rst b/docs/data-rw/nosql/index.rst index 16d0193d..3df58b92 100644 --- a/docs/data-rw/nosql/index.rst +++ b/docs/data-rw/nosql/index.rst @@ -1,17 +1,17 @@ -NoSQL-Datenbanken -================= +NoSQL databases +=============== -Bisher gibt es keine einheitliche Definition von NoSQL, die meisten -NoSQL-Datenbanksysteme haben jedoch meist folgendes gemeinsam: +So far there is no uniform definition of NoSQL, but most NoSQL database systems +usually have the following in common: -* kein relationales Datenmodell -* verteilte und horizontale Skalierbarkeit -* keine oder schwache Schemarestriktionen -* einfache API -* kein :term:`ACID`, sondern :term:`Eventual Consistency` oder :term:`BASE` als - Konsistenzmodell +* no relational data model +* distributed and horizontal scalability +* no or weak schema restrictions +* simple API +* no :term:`ACID`, but :term:`Eventual consistency` or :term:`BASE` as the + consistency model -NoSQL-Datenbanken lassen sich untergliedern in +NoSQL databases can be divided into .. toctree:: :titlesonly: @@ -24,12 +24,12 @@ NoSQL-Datenbanken lassen sich untergliedern in object-db xml-db -Bedeutende Konzepte und Technologien von NoSQL-Datenbanken sind +Major concepts and technologies of NoSQL databases are * :term:`MapReduce` -* :term:`CAP-Theorem` -* :term:`Eventual Consistency` und :term:`BASE` -* :term:`Konsistente Hashfunktion` -* :term:`MVCC – Multiversion Concurrency Control` -* :term:`Vektoruhr` +* :term:`CAP theorem` +* :term:`Eventual consistency` and :term:`BASE` +* :term:`Consistent hash function` +* :term:`MVCC – Multiversion RCncurrency Control` +* :term:`Vector clock` * :term:`Paxos` diff --git a/docs/data-rw/nosql/key-value-store.rst b/docs/data-rw/nosql/key-value-store.rst index be584044..f3726372 100644 --- a/docs/data-rw/nosql/key-value-store.rst +++ b/docs/data-rw/nosql/key-value-store.rst @@ -1,13 +1,13 @@ -Schlüssel-Werte-Datenbanksysteme -================================ +Key-value database systems +========================== -Schlüssel-Werte-Datenbanken, auch Key Value Stores genannt, speichern -:term:`Schlüssel/Wert-Paare `. +Key-value databases, also known as key value stores, store :term:`key/value +pairs `. -Datenbanksysteme +Database systems ---------------- -Schlüssel/Wert-Datenbanksysteme sind z.B. Riak, Cassandra, Redis und MongoDB. +Key/value database systems are e.g. Riak, Cassandra, Redis and MongoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Home** | `Riak`_ | `Cassandra`_ | `Redis`_ | `MongoDB`_ | @@ -16,38 +16,35 @@ Schlüssel/Wert-Datenbanksysteme sind z.B. Riak, Cassandra, Redis und MongoDB. +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ | **Docs** | `docs.riak.com`_ | `cassandra.apache.org/doc/`_ | `redis.io/documentation`_ | `docs.mongodb.com`_ | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anwendungsgebiete** | Session storage, Log data, | Georedundanz, hohe | Session Cache, Full Page | IoT, Mobile apps, CMS, | -| | Sensor data, CMS | Schreibgeschwindigkeit, | Cache (FPC), Queues, Pub/Sub | `einfache Geodaten`_, … | -| | | demokratische Peer-to-peer | | | -| | | (P2P)-Architektur, Daten mit | | | -| | | definierter Lebenszeit | | | -| | | | | | +| **Application areas** | Session storage, Log data, | Georedundancy, high writing | Session Cache, Full Page | IoT, Mobile apps, CMS, | +| | Sensor data, CMS | speed, democratic peer-to-peer | Cache (FPC), Queues, Pub/Sub | `simple geospatial data`_, … | +| | | (P2P) architecture, data with | | | +| | | a defined lifetime | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Entwicklungssprache**| Erlang | Java | ANSI C | C++ | +| **Development | Erlang | Java | ANSI C | C++ | +| language** | | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Lizenzen** | Apache License 2.0 | Apache License 2.0 | BSD-3-Clause License | Server Side Public License | +| **Licenses** | Apache License 2.0 | Apache License 2.0 | BSD-3-Clause License | Server Side Public License | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Datenmodell** | Im Wesentlichen | :term:`Column Family` | Schlüssel werden als | Flexibles Schema mit | -| | :term:`Schlüssel/Wert-Paar` | entsprechen Tabellen, | Zeichenkette gespeichert, | denormalisiertem Modell | -| | | *Keyspaces* Datenbanken; keine | Werte als Zeichenkette, Hashes,| | -| | | logische Struktur, kein Schema | Listen, Sets und sortierten | | -| | | | Sets | | +| **Data model** | Essentially | :term:`Column Family` | Keys are stored as strings, | Flexible scheme with | +| | :term:`Key/value pair` | correspond to tables, keyspaces| values as strings, hashes, | denormalised model | +| | | to databases; no logical | lists, sets and sorted sets | | +| | | structure, no scheme | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Query-Langauge** | Keyfilter, :term:`MapReduce`, | `Cassandra Query Language | | jQuery, :term:`MapReduce` | -| | Link-Walking, keine Ad-hoc | (CQL)`_ | | | -| | Queries möglich | | | | +| **Query langauge** | Keyfilter, :term:`MapReduce`, | `Cassandra Query Language | | jQuery, :term:`MapReduce` | +| | Link walking, no ad hoc queries| (CQL)`_ | | | +| | possible | | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Transaktionen, | :term:`ACID` | :term:`Eventual Consistency` | in-memory, asynchron on disc | :term:`Two-phase locking (2PL)`| -| Nebenläufigkeit** | | | mit *Append Only File Mode* | | +| **Transactions, | :term:`ACID` | :term:`Eventual Consistency` | in-memory, asynchronous on disc| :term:`Two-phase locking (2PL)`| +| concurrency** | | | with *Append Only File Mode* | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Replikation, | Multi-Master-Replikation | SimpleStrategy, | Master-N-Slaves-Replikation, | Master-Slave-Replikation, | -| Skalierung** | | NetworkTopologyStrategy und | Sharding mittels | Auto-Sharding | -| | | OldNetworkTopologyStrategy | :term:`consistent hashing | | -| | | | ` | | +| **Replication, | Multi-master replikation | SimpleStrategy, |Master-N-Slaves replikation, | Master-Slave replikation, | +| skaling** | | NetworkTopologyStrategy and |Sharding using | Auto-Sharding | +| | | OldNetworkTopologyStrategy |:term:`Consistent hash function`| | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ -| **Anmerkungen** | | Siehe auch `Scylla`_, eine | Siehe auch `KeyDB`_, ein Fork | `BSON` mit einre maximalen | -| | | Cassandra-kompatible | von Redis mit Multithreading. | Dokumentengröße von 16 MB. | -| | | Reimplementierung in C. | | | +| **Remarks** | | See also `Scylla`_, a | See also `KeyDB`_, a fork | `BSON` with a maximum | +| | | Cassandra-compatible | from Redis with multithreading.| document size of 16 MB. | +| | | reimplementation in C. | | | +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+ .. _`Riak`: https://riak.com/ @@ -62,7 +59,7 @@ Schlüssel/Wert-Datenbanksysteme sind z.B. Riak, Cassandra, Redis und MongoDB. .. _`cassandra.apache.org/doc/`: https://cassandra.apache.org/doc/latest/ .. _`redis.io/documentation`: https://redis.io/documentation .. _`docs.mongodb.com`: https://docs.mongodb.com/ -.. _`einfache Geodaten`: https://docs.mongodb.com/manual/core/geospatial-indexes/ +.. _`simple geospatial data`: https://docs.mongodb.com/manual/core/geospatial-indexes/ .. _`Cassandra Query Language (CQL)`: https://cassandra.apache.org/doc/latest/cql/ .. _`Scylla`: https://www.scylladb.com/ .. _`KeyDB`: https://github.com/JohnSully/KeyDB diff --git a/docs/data-rw/nosql/object-db.rst b/docs/data-rw/nosql/object-db.rst index a04c1320..b0c367ce 100644 --- a/docs/data-rw/nosql/object-db.rst +++ b/docs/data-rw/nosql/object-db.rst @@ -1,56 +1,52 @@ -Objektdatenbanksysteme -====================== +Object database systems +======================= -Viele Programmiersprachen legen eine objektorientierte Programmierung nahe und -daher erscheint die Speicherung dieser Objekte natürlich. Daher liegt nahe, den -kompletten Prozess von der Implementierung bis zur Speicherung einheitlich und -einfach zu gestalten. Im Einzelnen sind die Vorteile: +Many programming languages suggest object-oriented programming, so storing these +objects seems natural. It therefore makes sense to design the entire process +from implementation to storage uniformly and simply. In detail, the advantages +are: -Natürliche Modellierung und Repräsentation von Problemen - Probleme lassen sich auf eine Weise modellieren, die der menschlichen - Denkweise sehr nahe kommen. -Übersichtlicher, lesbarer und verständlicher - Die Daten und die auf diesen operierenden Funktionen werden zu einer Einheit - zusammengefasst, wodurch die Programme übersichtlicher, lesbarer und - verständlicher werden. -Modular und wiederverwendbar - Programmteile lassen sich einfach und flexibel wiederverwenden. -Erweiterbar - Programme lassen sich einfach erweitern und an geänderte Anforderungen - anpassen. +Natural modeling and representation of problems + Problems can be modeled in ways that are very close to the human way of + thinking. +Clearer, more readable and more understandable + The data and the functions operating on them are combined into one unit, + making the programs clearer, more readable and easier to understand. +Modular and reusable + Program parts can be easily and flexibly reused. +Expandable + Programs can be easily expanded and adapted to changed requirements. Object-relational impedance mismatch ------------------------------------ -Objektorientierte Programmierung und relationale Datenhaltung sind aus -verschiedenen Gründen problematisch. So ist ein wichtiges Konzept der OOP zur -Umsetzung komplexer Modelle die Vererbung. Im relationalen Paradigma gibt es -jedoch nichts vergleichbares. Zur Umwandlung entsprechender Klassenhierarchien -in ein relationales Modell wurden objekt-relationale Mapper, ORM entwickelt, wie -z.B. :doc:`../postgresql/sqlalchemy`. Prinzipiell gibt es zwei verschiedene -Ansätze für ein ORM, wobei in beiden Fällen eine Tabelle für eine Klasse -angelegt wird: +Object-oriented programming and relational data storage are problematic for +various reasons. Inheritance is an important concept in OOP for implementing +complex models. In the relational paradigm, however, there is nothing like it. +Object-relational mappers, ORM, such as :doc:`../postgresql/sqlalchemy`, were +developed to convert corresponding class hierarchies into a relational model. In +principle there are two different approaches for an ORM, whereby in both cases a +table is created for a class: -Vertikale Partitionierung - Die Tabelle enthält nur die Attribute der entsprechenden Klasse sowie einen - Fremdschlüssel für die Tabelle der Oberklasse. Für jedes Objekt wird ein dann - ein Eintrag in der zur Klasse gehörenden Tabelle sowie in den Tabellen aller - Oberklassen angelegt. Beim Zugriff müssen die Tabellen mit Joins verbunden - werden, wodurch es bei komplexen Modellen zu erheblichen - Performance-Verlusten kommen kann. -Horizontale Partitionierung - Jede Tabelle enthält die Attribute der zugehörigen Klasse sowie aller - Oberklassen. Bei einer Änderung der Oberklasse müssen dann jedoch die - Tabellen aller abgeleiteten Klassen ebenfalls aktualisiert werden. +Vertical partitioning + The table only contains the attributes of the corresponding class and a + foreign key for the table of the superclass. An entry is then created for + each object in the table belonging to the class and in the tables of all + superclasses. When accessing the tables, joins must be used, which can + lead to significant performance losses in complex models. +Horizontal partitioning + Each table contains the attributes of the associated class and all + superclasses. If the superclass is changed, however, the tables of all + derived classes must also be updated. -Grundsätzlich müssen bei der Kombination von OOP und relationaler Datenhaltung -immer zwei Datenmodelle erstellt werden. Dies macht diese Architektur deutlich -komplexer, fehleranfälliger und in der Wartung aufwändiger. +Basically, when combining OOP and relational data management, two data models +must always be created. This makes this architecture significantly more complex, +more error-prone and more time-consuming to maintain. -Datenbanksysteme +Database systems ---------------- -Beispiele für Objektdatenbanksysteme sind ZODB und Objectivity/DB. +Examples of object database systems are ZODB and Objectivity/DB. +------------------------+----------------------------------------+----------------------------------------+ | **Home** | `ZODB`_ | `Objectivity/DB`_ | @@ -59,24 +55,26 @@ Beispiele für Objektdatenbanksysteme sind ZODB und Objectivity/DB. +------------------------+----------------------------------------+----------------------------------------+ | **Docs** | `www.zodb.org/en/latest/tutorial.html`_| `Objectivity/DB Basics Tutorial`_ | +------------------------+----------------------------------------+----------------------------------------+ -| **Anwendungsgebiete** | Plone, Pyramid, BTrees, volatile Daten | IoT, Telekommunikation, Netzwerktechnik| +| **Application areas** | Plone, Pyramid, BTrees, volatile data | IoT, telecommunications, network | +| | | technology | +------------------------+----------------------------------------+----------------------------------------+ -| **Entwicklungssprache**| Python | Java | +| **Development | Python | Java | +| language** | | | +------------------------+----------------------------------------+----------------------------------------+ -| **Lizenzen** | Zope Public License (ZPL) 2.1 | kommerziell | +| **Licenses** | Zope Public License (ZPL) 2.1 | commercially | +------------------------+----------------------------------------+----------------------------------------+ -| **Datenmodell** | PersistentList, PersistentMapping, | Objects, References, Relationships, | -| | BTree | Indexes, Trees und Collections | +| **Data model** | PersistentList, PersistentMapping, | Objects, References, Relationships, | +| | BTree | Indexes, Trees and Collections | +------------------------+----------------------------------------+----------------------------------------+ -| **Query-Langauge** | | Objectivity/DB predicate query language| +| **Query langauge** | | Objectivity/DB predicate query language| +------------------------+----------------------------------------+----------------------------------------+ -| **Transaktionen, | :term:`ACID` | :term:`ACID` | -| Nebenläufigkeit** | | | +| **Transactions, | :term:`ACID` | :term:`ACID` | +| concurrency** | | | +------------------------+----------------------------------------+----------------------------------------+ -| **Replikation, | `ZODB Replication Services (ZRS)`_ | Quorum basierte synchrone Replikation | -| Skalierung** | | | +| **Replication, | `ZODB Replication Services (ZRS)`_ | Quorum based synchronous replication | +| skaling** | | | +------------------------+----------------------------------------+----------------------------------------+ -| **Anmerkungen** | | | +| **Remarks** | | | +------------------------+----------------------------------------+----------------------------------------+ .. _`ZODB`: hhttp://www.zodb.org/ diff --git a/docs/data-rw/nosql/xml-db.rst b/docs/data-rw/nosql/xml-db.rst index 30afc8f7..dbc648ad 100644 --- a/docs/data-rw/nosql/xml-db.rst +++ b/docs/data-rw/nosql/xml-db.rst @@ -1,14 +1,14 @@ -XML-Datenbanksysteme +XML database systems ==================== -XML-Datenbanken sind in der Lage, XML-Dokumente gegen ein XML-Schema oder eine -DTD zu validieren. Darüberhinaus unterstützen sie mindestens :term:`XPATH`, -:term:`XQuery` und :term:`XSLT`. +XML databases are able to validate XML documents against an XML schema or a DTD. +In addition, they support at least :term:`XPATH`, :term:`XQuery` and +:term:`XSLT`. -Datenbanksysteme +Database systems ---------------- -Beispiele für XML-Datenbanksysteme sind eXist und MonetDB. +Examples of XML database systems are eXist and MonetDB. +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ | **Home** | `eXist`_ | `MonetDB`_ | `BaseX`_ | @@ -17,24 +17,25 @@ Beispiele für XML-Datenbanksysteme sind eXist und MonetDB. +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ | **Docs** | `exist-db.org/exist/apps/doc/documentation`_ | `www.monetdb.org/Documentation`_ | `docs.basex.org`_ | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Anwendungsgebiete** | CMS | CMS, Date-Warehouse, Data mining | CMS | +| **Application areas** | CMS | CMS, Date-Warehouse, Data mining | CMS | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Entwicklungssprache**| Java | C | Java | +| **Development | Java | C | Java | +| language** | | | | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Lizenzen** | LGPL-2.1 License | Mozilla Public License 2.0 | BSD-3-Clause License | +| **Licenses** | LGPL-2.1 License | Mozilla Public License 2.0 | BSD-3-Clause License | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Datenmodell** | XML | XML, Spaltenorientierte Datenstruktur | XML, `Geo-Daten`_ | +| **Data model** | XML | XML, column-oriented data structure | XML, `geographic data`_ | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Query-Langauge** | :term:`XQuery`, :term:`XPATH` | SQL | :term:`XQuery`, :term:`XPATH` | +| **Query langauge** | :term:`XQuery`, :term:`XPATH` | SQL | :term:`XQuery`, :term:`XPATH` | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Transaktionen, | | :term:`Optimistic Concurrency ` | :term:`ACID`, XQuery Locks | -| Nebenläufigkeit** | | | | +| **Transactions, | | :term:`Optimistic Concurrency ` | :term:`ACID`, XQuery Locks | +| concurrency** | | | | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Replikation, | Master-Slave-Replikation | Transaktionsreplikation | | -| Skalierung** | | | | +| **Replication, | Master-slave replication | Transaction replication | | +| skaling** | | | | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ -| **Anmerkungen** | | Mit R können Analysen direkt auf Datenbankebene| | -| | | durchgeführt werden. | | +| **Remarks** | | With R, analyzes can be carried out directly | | +| | | at the database level. | | +------------------------+------------------------------------------------+------------------------------------------------+------------------------------------------------+ .. _`eXist`: http://exist-db.org/ @@ -46,4 +47,4 @@ Beispiele für XML-Datenbanksysteme sind eXist und MonetDB. .. _`exist-db.org/exist/apps/doc/documentation`: https://exist-db.org/exist/apps/doc/documentation .. _`www.monetdb.org/Documentation`: https://www.monetdb.org/Documentation .. _`docs.basex.org`: https://docs.basex.org/wiki/Main_Page -.. _`Geo-Daten`: https://docs.basex.org/wiki/Geo_Module +.. _`geographic data`: https://docs.basex.org/wiki/Geo_Module diff --git a/docs/data-rw/overview.rst b/docs/data-rw/overview.rst index 26996cb9..42f5ee2d 100644 --- a/docs/data-rw/overview.rst +++ b/docs/data-rw/overview.rst @@ -1,8 +1,8 @@ -Überblick -========= +Overview +======== -Entfernte Speichermedien ------------------------- +Remote storage media +-------------------- `boto3 `_ S3 @@ -16,26 +16,25 @@ Entfernte Speichermedien `PyArrow `_ HDFS -Geodaten --------- +Geodata +------- `Rasterio `_ - liest und schreibt GeoTIFF und andere Formen von Raster-Datasets + reads and writes GeoTIFF and other forms of raster datasets. `Geospatial Data Abstraction Library (GDAL) `_ - bietet eine Low-Level-, aber leistungsfähigere API zum Lesen und Schreiben - hunderter Datenformate. + provides a low-level but more powerful API for reading and writing hundreds + of data formats. `satpy `_ - Einfach zu verwendende API für Satellitenbildformate von Sensoren wie - `MODIS `_, `Sentinel-2 + Easy to use API for sensors of satellite images like `MODIS + `_, `Sentinel-2 `_ etc. `sentinelsat `_ - Suchen und Herunterladen von Copernicus Sentinel-Satellitenbildern über - Befehlszeile oder Python. + Find and download Copernicus Sentinel satellite imagery using command line + or Python. `fiona `_ - liest und schreibt ``*shp``- und ``*json``-Daten und viele weitere Formate. + reads and writes ``*shp``- and ``*json`` data and many other formats. `pyproj `_ - Python-Schnittstelle zu `PROJ `_, einer Bibliothek für - kartografische Projektionen und Koordinatentransformationen. + Python interface to `PROJ `_, a library for cartographic + projections and coordinate transformations. `pyModis `_ - Sammlung von Python-Skripten zum Herunterladen und Mosaizieren von - MODIS-Daten. + Collection of Python scripts for downloading and mosaicking MODIS data. diff --git a/docs/data-rw/postgresql/alembic.rst b/docs/data-rw/postgresql/alembic.rst index 5bd73e8c..8677976e 100644 --- a/docs/data-rw/postgresql/alembic.rst +++ b/docs/data-rw/postgresql/alembic.rst @@ -1,21 +1,21 @@ Alembic ======= -`Alembic `_ basiert auf SQLAlchemy und dient als -Datenbankmigrationswerkzeug mit den folgenden Funktionen: +`Alembic `_ is based on SQLAlchemy and serves +as a database migration tool with the following functions: -* ``ALTER``-Anweisungen an eine Datenbank ausgeben um die Strukturen von - Tabellen und anderen Konstrukten zu ändern -* System zum Erstellen von Migrationsskripten. Optional kann auch die - Reihenfolge der Schritte für das Downgrade angegeben werden. -* Die Skripte werden in einer bestimmten Reihenfolge ausgeführt. +* ``ALTER`` statements to a database to change the structure of tables and other + constructs +* System for creating migration scripts. Optionally, the sequence of steps for + the downgrade can also be specified. +* The scripts are executed in a specific order. -Migrationsumgebung erstellen +Create migration environment ---------------------------- -Das Migration Environment ist ein Verzeichnis, das für eine bestimmte Anwendung -spezifisch ist. Sie wird mit dem ``ini``-Befehl von Alembic erstellt und -anschließend zusammen mit dem Quellcode der Anwendung verwaltet. +The Migration Environment is a directory that is specific to a particular +application. It is created with the Alembic ``ini`` command and then managed +along with the application’s source code. :: @@ -30,10 +30,7 @@ anschließend zusammen mit dem Quellcode der Anwendung verwaltet. Please edit configuration/connection/logging settings in '/path/to/myproject/alembic.ini' before proceeding. -Die Struktur eines solchen Migrationsumgebung kann später dann z.B. so -aussehen: - -:: +The structure of such a migration environment can e.g. look like this:: myproject/ └── alembic @@ -46,11 +43,9 @@ aussehen: ├── 3512b954651e_add_account.py └── 3adcc9a56557_rename_username_field.py -Vorlagen --------- - -Alembic erhält eine Reihe von Vorlagen, die mit ``list`` angezeigt werden -können:: +Templates +--------- +Alembic includes a number of templates that can be displayed with list:: $ alembic list_templates Available templates: @@ -63,10 +58,10 @@ können:: alembic init --template pylons ./scripts -ini-Datei konfigurieren ------------------------ +Configure ``ini`` file +---------------------- -Die mit der ``generic``-Vorlage erstellte Datei sieht folgendermaßen aus:: +The file created with the ``generic`` template looks like this:: # A generic, single database configuration. @@ -143,27 +138,27 @@ Die mit der ``generic``-Vorlage erstellte Datei sieht folgendermaßen aus:: datefmt = %H:%M:%S ``%(here)s`` - Ersetzungsvariable zum Erstellen absoluter Pfade + Replacement variable for creating absolute paths ``file_template`` - Dies ist das Namensschema, das zum Generieren neuer Migrationsdateien - verwendet wird. Zu den verfügbaren Variablen gehören: + This is the naming scheme used to generate new migration files. The + available variables include: ``%%(rev)s`` - Revision-ID + Revision ID ``%%(slug)s`` - Verkürzte Revisionsnachricht + Abbreviated revision message ``%%(year)d, %%(month).2d, %%(day).2d, %%(hour).2d, %%(minute).2d, %%(second).2d`` - Erstellungszeitpunkt + Creation time -Erstellen eines Migrationsskripts ---------------------------------- +Create a migration script +------------------------- -Eine neue Revision kann erstellt werden mit:: +A new revision can be created with:: $ alembic revision -m "create account table" Generating /path/to/yourproject/alembic/versions/1975ea83b712_create_account_table.py...done -Die Datei ``1975ea83b712_create_account_table.py`` sieht dann folgendermaßen aus:: +Then the file ``1975ea83b712_create_account_table.py`` looks like this:: """create account table @@ -188,15 +183,15 @@ Die Datei ``1975ea83b712_create_account_table.py`` sieht dann folgendermaßen au pass ``down_revision`` - Variable, die Alembic mitteilt, in welcher Reihenfolge die Migrationen - ausgeführt werden sollen, z.B.:: + Variable that tells Alembic in which order the migrations should be carried + out, e.g.:: # revision identifiers, used by Alembic. revision = 'ae1027a6acf' down_revision = '1975ea83b712' ``upgrade``, ``downgrade`` - z.B.:: + e.g.:: def upgrade(): op.create_table( @@ -209,49 +204,47 @@ Die Datei ``1975ea83b712_create_account_table.py`` sieht dann folgendermaßen au def downgrade(): op.drop_table('account') - ``create_table()`` und ``drop_table()`` sind Alembic-Direktiven. Einen - Überblick über alle Alembic-Direktiven erhaltet ihr in der `Operation Reference + ``create_table()`` and ``drop_table()`` are Alembic directives. You can get + an overview of all Alembic directives in the `Operation Reference `_. -Ausführen von Migration ------------------------ +Run migration +------------- -Erste Migration:: +First migration:: $ alembic upgrade head INFO [alembic.context] Context class PostgresqlContext. INFO [alembic.context] Will assume transactional DDL. INFO [alembic.context] Running upgrade None -> 1975ea83b712 -Wir können auch direkt auf Revisionsnummern verweisen:: +We can also refer directly to revision numbers:: $ alembic upgrade ae1 -Auch relative Migrationen können angestoßen werden:: +Relative migrations can also be initiated:: $ alembic upgrade +2 -oder:: +or:: $ alembic downgrade -1 -oder:: +or:: $ alembic upgrade ae10+2 -Informationen anzeigen ----------------------- +Display Information +------------------- -Aktuelle Version - :: +Current version:: $ alembic current INFO [alembic.context] Context class PostgresqlContext. INFO [alembic.context] Will assume transactional DDL. Current revision for postgresql://scott:XXXXX@localhost/test: 1975ea83b712 -> ae1027a6acf (head), Add a column -Historie - :: +History:: $ alembic history --verbose @@ -275,15 +268,15 @@ Historie Revises: Create Date: 2014-11-20 13:02:46.257104 - Die Historie kann auch spezifischer angezeigt werden:: + The history can also be displayed more specifically:: $ alembic history -r1975ea:ae1027 - oder:: + or:: $ alembic history -r-3:current - oder:: + or:: $ alembic history -r1975ea: diff --git a/docs/data-rw/postgresql/db-api.rst b/docs/data-rw/postgresql/db-api.rst index 816009d6..1794964f 100644 --- a/docs/data-rw/postgresql/db-api.rst +++ b/docs/data-rw/postgresql/db-api.rst @@ -1,27 +1,27 @@ DB-API 2.0 ========== -Die Python-API für Datenbank-Konnektoren ist einfach zu bedienen und zu -verstehen. Die beiden wesentlichen Konzepte sind: +The Python API for database connectors is easy to use and understand. The two +main concepts are: Connection `Connection Objects - `_ erlauben - die folgenden Methoden: + `_ allow the + following methods: ``connect(parameters…)`` - öffnet die Verbindung zur Datenbank + opens the connection to the database ``.close()`` - schließt die Verbindung zur Datenbank + closes the connection to the database ``.commit()`` - überträgt die ausstehende Transaktion zur Datenbank + transfers the outstanding transaction to the database ``.rollback()`` - Diese Methode ist optional da nicht alle Datenbanken das Zurückrollen - von Transaktionen erlauben. + This method is optional as not all databases allow transactions to be + rolled back. ``.cursor ()`` - Rückgabe eines neuen Corsor-Objekts über die Verbindung + Return of a new cursor object via the connection. - Beispiel:: + Example:: import driver @@ -38,16 +38,16 @@ Connection conn.close() Cursor - `Cursorobjekte `_ - werden zum Verwalten des Kontexts einer ``.fetch*()``-Methode verwendet. + `Cursor objects `_ + are used to manage the context of a ``.fetch*()`` method. - Dabei sind Cursor, die in derselben *Connection* erstellt werden, nicht - isoliert voneinander. + Cursors that are created in the same connection are not isolated from one + another. - Es gibt zwei Attribute für Cursor-Objekte: + There are two attributes for cursor objects: ``.description`` - enthält die folgenden sieben Elemente: + contains the following seven elements: #. ``name`` #. ``type_code`` @@ -57,17 +57,15 @@ Cursor #. ``scale`` #. ``null_ok`` - Die ersten beiden Elemente (``name`` und ``type_code``) sind - obligatorisch, die anderen fünf sind optional und werden auf - ``None`` gesetzt, wenn keine sinnvollen Werte angegeben - werden können. + The first two elements (``name`` and ``type_code``) are mandatory, the + other five are optional and are set to ``None`` if no meaningful values + can be specified. ``.rowcount`` - gibt die Anzahl der Zeilen an, die der letzte Aufruf von - `` .execute*()`` mit ``SELECT``, ``UPDATE`` oder ``INSERT`` - ergab. + indicates the number of lines that the last call of ``.execute*()`` with + ``SELECT``, ``UPDATE`` or ``INSERT`` resulted in. - Beispiel:: + Example:: cursor = conn.cursor() cursor.execute(""" diff --git a/docs/data-rw/postgresql/fdw.rst b/docs/data-rw/postgresql/fdw.rst index 66d350f1..8517ca5d 100644 --- a/docs/data-rw/postgresql/fdw.rst +++ b/docs/data-rw/postgresql/fdw.rst @@ -1,46 +1,45 @@ Foreign Data Wrappers (FDW) =========================== -2003 wurde SQL erweitert um SQL/MED (*SQL Management of External Data*). -PostgreSQL 9.1 unterstützte dies *read-only*, 9.3 dann auch schreibend. -Seitdem sind eine Reihe von Foreign Data Wrappers (FDW) für PostgreSQL -entwickelt worden. +In 2003, SQL was expanded to include SQL/MED (SQL Management of External +Data). PostgreSQL 9.1 supports this read-only, 9.3 then also write. Since then, +a number of Foreign Data Wrappers (FDW) have been developed for PostgreSQL. -Im Folgenden nur eine kleine Auswahl der bekanntesten FDW: +The following is just a small selection of the best-known FDWs: .. note:: - Beachtet bitte, dass die meisten dieser Wrapper nicht offiziell von der - PostgreSQL Global Development Group (PGDG) unterstützt werden. + Please note that most of these wrappers are not officially supported by the + PostgreSQL Global Development Group (PGDG). -Generische SQL-Wrapper ----------------------- +Generic SQL wrappers +-------------------- ODBC - Nativer ODBC FDW für PostgreSQL ≥9.5 + Native ODBC FDW for PostgreSQL ≥9.5 * `GitHub `_ Multicorn - `Multicorn `_ erleichtert die Entwicklung von FDWs. - So verwendet z.B. `SQLAlchemy `_ `Multicorn - `_ um seine Daten in PostgreSQL zu speichern. + `Multicorn `_ makes it easy to develop FDWs. For + example, `SQLAlchemy `_ uses Multicorn to save + your data in PostgreSQL. * `GitHub `_ * `PGXN `_ * `Docs `_ VirtDB - Nativer Zugang zu VirtDB (SAP ERP, Oracle RDBMS) + Native access to VirtDB (SAP ERP, Oracle RDBMS) * `GitHub `_ -Spezifische SQL-Wrapper ------------------------ +Specific SQL wrappers +--------------------- postgres_fdw - Mit `postgres_fdw - `_ kann auf Daten - aus anderen PostgreSQL-Servern zugegriffen werden. + With `postgres_fdw + `_ data from + other PostgreSQL servers can be accessed. * `Git `_ @@ -48,114 +47,114 @@ postgres_fdw * `Docs `_ Oracle - FDW für Oracle-Datenbanken + FDW for Oracle databases * `GitHub `_ * `PGXN `_ * `Docs `_ MySQL - FDW für MySQL ab PostgrSQL≥9.3 + FDW for MySQL from PostgreSQL≥9.3 * `GitHub `_ * `PGXN `_ SQLite - FDW für SQLite3 + FDW for SQLite3 * `GitHub `_ * `PGXN `_ * `Docs `_ -NoSQL-Database-Wrappers +NoSQL database wrappers ----------------------- Cassandra - FDW für `Cassandra `_ + FDW for `Cassandra `_ * `GitHub `_ * `rankactive `_ Neo4j - FWD für `Neo4j `_, die auch eine Cypher-Funktion für - PostgreSQL bereitstellt + FWD for `Neo4j `_, which also provides a cypher + function for PostgreSQL * `GitHub `_ * `Docs `_ Redis - FDW für `Redis `_ + FDW for `Redis `_ * `GitHub `_ Riak - FDW für `Riak `_ + FDW for `Riak `_ * `GitHub `_ -File-Wrappers +File wrappers ------------- CSV - Offizielle Erweiterung für PostgreSQL 9.1 + Official extension for PostgreSQL 9.1 * `Git `_ * `Docs `_ JSON - FDW für JSON-Dateien + FDW for JSON files * `GitHub `_ - * `Beispiel `_ + * `Example `_ XML - FDW für XML-Dateien + FDW for XML files * `GitHub `_ * `PGXN `_ -Geo Wrappers +Geo wrappers ------------ GDAL/OGR - FDW für den `GDAL/OGR `_-Treiber einschließlich - Datenbanken wie Oracle und SQLite sowie Dateiformate wie MapInfo, CSV, - Excel, OpenOffice, OpenStreetMap PBF und XML. + FDW for the `GDAL/OGR `_ driver including databases + like Oracle and SQLite as well as file formats like MapInfo, CSV, Excel, + OpenOffice, OpenStreetMap PBF and XML. * `GitHub `_ Geocode/GeoJSON - Eine Sammlung von FDWs für PostGIS + A collection of FDWs for PostGIS * `GitHub `_ Open Street Map PBF - FDW für `Open Street Map PBF + FDW for `Open Street Map PBF `_ * `GitHub `_ -Generische Web-Wrappers ------------------------ +Generic web wrappers +-------------------- ICAL - FDW für ICAL + FDW for ICAL * `GitHub `_ * `Docs `_ IMAP - FDW für das *Internet Message Access Protocol (IMAP)* + FDW for the Internet Message Access Protocol (IMAP) * `Docs `_ RSS - FDQ für RSS-Feeds + FDQ for RSS feeds * `Docs `_ .. seealso:: - * `PostgreSQL Wiki + * `PostgreSQL wiki `_ - * `PGXN-Website `_ + * `PGXN website `_ diff --git a/docs/data-rw/postgresql/index.rst b/docs/data-rw/postgresql/index.rst index 17b18d70..193860b1 100644 --- a/docs/data-rw/postgresql/index.rst +++ b/docs/data-rw/postgresql/index.rst @@ -1,39 +1,39 @@ PostgreSQL ========== -Grundfunktionen ---------------- +Basic funtions +-------------- -ACID-konform - ACID (**A** tomicity, **C** onsistency, **I** solation, **D** urability) ist - eine Reihe von Eigenschaften, die Datenbanktransaktionen erfüllen sollten - um auch im Störungsfall weiterhin die Gültigkeit der Daten gewährleisten - zu können. +ACID compliant + ACID (**A** tomicity, **C** onsistency, **I** solation, **D** urability) is + a series of properties that database transactions should fulfill to + guarantee the validity of the data even in the event of a fault. SQL:2011 - Mit `temporal_tables `_ wird - auch der SQL-Standard ISO/IEC 9075:2011 erfüllt, u.a. durch: + Ttemporal_tables `_ also meet + the SQL standard ISO/IEC 9075:2011, including: - * Time Period definitions + * Time period definitions * Valid time tables * Transaction time tables (system-versioned tables) with time-sliced and sequenced queries -Datentypen - Folgende Datentypen werden out of the box unterstützt: +Data types + The following data types are supported out of the box: - * primitiven Datentypen: Integer, Numeric, String, Boolean - * Strukturierte Datentypen: Date/Time, Array, Range, UUID - * Dokumenttypen: JSON/JSONB, XML, Key-value (`Hstore - `_) - * Geometrische Datentypen: Point, Line, Circle, Polygon - * Anpassungen: Composite, Custom Types + * primitive data types: Integer, Numeric, String, Boolean -Transactional Data Definition Language (DDL) - Transactional DDL wird via `Write-Ahead Logging - `_ realisiert. - Dabei sind auch große Änderungen möglich, nicht jedoch *add* und *drop* von - Datenbanken und Tabellen:: + * structured data types: Date/Time, Array, Range, UUID + + * document types: JSON/JSONB, XML, key-value (`Hstore + `_) + * geometric data types: point, line, circle, polygon + * adjustments: composite, custom Types + * transactional data definition language (DDL) + + Transactional DDL is implemented via `write-ahead logging + `_. Big changes + are also possible, but not adding and dropping databases and tables:: $ psql mydb mydb=# DROP TABLE IF EXISTS foo; @@ -51,25 +51,25 @@ Transactional Data Definition Language (DDL) ERROR: relation "foo" does not exist Concurrent Index - PostgreSQL kann Indizes erstellen ohne Schreibzugriffe auf Tabellen sperren - zu müssen. + PPostgreSQL can create indexes without having to lock write access to + tables. .. seealso:: `Building Indexes Concurrently `_ -Erweiterungen - PostgreSQL kann einfach erweitert werden. Das mit dem Quellcode gelieferte - `contrib/ `_-Verzeichnis - enthält verschiedene Erweiterungen, die in `Appendix F - `_ beschrieben sind. - Andere Erweiterungen sind unabhängig entwickelt worden, wie z.B. `PostGIS - `_ oder `Slony-I `_. +Extensions + PostgreSQL can easily be extended. The `contrib/ + `_ directory + supplied with the source code contains various extensions that are described + in `Appendix F `_. Other + extensions have been developed independently, such as :doc:`postgis/index` + or `Slony-I `_. Common Table Expression `WITH Queries (Common Table Expressions) - `_ unterteilt - komplexe Anfragen in einfachere Anfragen, z.B.:: + `_ divides + complex queries into simpler queries, e.g .:: WITH regional_insolation AS ( SELECT region, SUM(amount) AS total_insolation @@ -81,9 +81,9 @@ Common Table Expression WHERE total_insolation > (SELECT SUM(total_insolation)/10 FROM regional_insolation) ) - Zudem gibt es auch noch einen ``RECURSIVE``-Modifier, der die - ``WITH``-Abfrage auf seine eigene Ausgabe verweist. Im folgenden ein - Beispiel zum Summieren der Zahlen von 1 bis 100:: + There is also a ``RECURSIVE`` modifier that refers the ``WITH`` query to its + own output. The following is an example of how to sum the numbers from 1 to + 100:: WITH RECURSIVE t (n) AS ( WERTE (1) @@ -94,23 +94,23 @@ Common Table Expression Multi-Version Concurrency Control (MVCC) `Multi-Version Concurrency Control - `_ erlaubt, dass zwei - oder mehr Sessions gleicheitig auf dieselben Daten zugreifen ohne dabei die - Integrität der Daten zu gefährden. + `_ allows two or more + sessions to access the same data at the same time without compromising the + integrity of the data. -Cross Platform - PostgreSQL läuft auf gängigen CPU-Architekturen wie ``x86``, ``PowerPC``, - ``Sparc``, ``ARM``, ``MIPS`` oder ``PA-RISC``. Auch die meisten - Betriebssysteme werden unterstützt: ``Linux``, ``Windows``, ``FreeBSD``, - ``OpenBSD``, ``NetBSD``, ``Mac OS``, ``AIX``, ``HP/UX`` und ``Solaris``. +Cross platform + PostgreSQL runs on common CPU architectures such as ``x86``, ``PowerPC``, + ``Sparc``, ``ARM``, ``MIPS`` or `PA-RISC```. Most operating systems are also + supported: ``Linux``, ``Windows``, ``FreeBSD``, ``OpenBSD``, ``NetBSD``, + ``Mac OS``, ``AIX``, ``HP/UX`` and ``Solaris``. .. seealso:: `explain.depesz.com `_ - Web-App, die PostgreSQLs `EXPLAIN - `_- und + Web app that visualises PostgreSQL’s `EXPLAIN + `_ and `ANALYZE `_ - -Anweisungen visualisiert. + statements. .. toctree:: :hidden: diff --git a/docs/data-rw/postgresql/orm.rst b/docs/data-rw/postgresql/orm.rst index b16a536e..1c8547f3 100644 --- a/docs/data-rw/postgresql/orm.rst +++ b/docs/data-rw/postgresql/orm.rst @@ -1,28 +1,27 @@ -Objektrelationale Abbildung -=========================== +Object-relational mapping +========================= - «Objektrelationale Abbildung (englisch object-relational mapping, ORM) ist - eine Technik der Softwareentwicklung, mit der ein in einer - objektorientierten Programmiersprache geschriebenes Anwendungsprogramm seine - Objekte in einer relationalen Datenbank ablegen kann.»[#]_ + «Object-relational mapping (…) in computer science is a programming + technique for converting data between incompatible type systems using + object-oriented programming languages.»[#]_ -.. [#] `Wikipedia: Objektrelationale Abbildung - `_ +.. [#] `Wikipedia: relational mapping + `_ -Im einfachsten Fall werden Klassen auf Tabellen abgebildet, wobei jedes Objekt einer -Tabellenzeile entspricht und jedem Attribut eine Tabellenspalte. +In the simplest case, classes are mapped to tables, with each object +corresponding to a table row and each attribute to a table column. -Um Vererbungshierarchien abzubilden gibt es im Wesentlichen drei verschiedene -Verfahren: +There are essentially three different methods of mapping inheritance +hierarchies: *Single Table* - Dabei wird eine Tabelle pro Vererbungshierarchie angelegt, wobei alle - Attribute der Basisklasse und aller davon abgeleiteten Klassen in einer - gemeinsamen Tabelle gespeichert wird. + One table is created for each inheritance hierarchy, with all attributes of + the base class and all classes derived from it being stored in a common + table. *Joined Table* oder *Class Table* - Dabei wird eine Tabelle je Unterklasse angelegt und für jede davon - abgeleitete Unterklasse eine weitere Tabelle. -*Table per Class* oder *Concrete Table* - Dabei werden die Attribute der abstrakten Basisklasse in die Tabellen für - die konkreten Unterklassen mit aufgenommen. Hierbei ist es jedoch nicht - möglich, mit einer Abfrage Instanzen verschiedener Klassen zu ermitteln. + A table is created for each subclass and a further table for each subclass + derived from it. +*Table per Class* or *Concrete Table* + The attributes of the abstract base class are included in the tables for the + specific subclasses. However, it is not possible to determine instances of + different classes with one query. diff --git a/docs/data-rw/postgresql/plang.rst b/docs/data-rw/postgresql/plang.rst index a535e539..5e8a30f8 100644 --- a/docs/data-rw/postgresql/plang.rst +++ b/docs/data-rw/postgresql/plang.rst @@ -1,19 +1,19 @@ -Prozedurale Programmiersprachen -=============================== +Procedural programming languages +================================ -Mit PostgreSQL können benutzerdefinierte Funktionen außer in SQL und C auch in -anderen Sprachen geschrieben werden. +With PostgreSQL, user-defined functions can be written in languages other than +SQL and C. -In der Standarddistribution von PostgreSQL stehen derzeit vier prozedurale -Sprachen zur Verfügung: +There are currently four procedural languages available in the standard +PostgreSQL distribution: * `PL/pgSQL `_ * `PL/Tcl `_ * `PL/Perl `_ * `PL/Python `_ -Es sind zusätzliche prozedurale Programmiersprachen verfügbar, die jedoch nicht -in der Kerndistribution enthalten sind: +Additional procedural programming languages are available but are not included +in the core distribution: * `PL/Java `_ * `PL/Lua `_ @@ -25,5 +25,5 @@ in der Kerndistribution enthalten sind: `External Procedural Languages `_ -Zusätzlich können andere Sprachen definiert werden, s. `Writing A Procedural +In addition, other languages can be defined, see also `Writing A Procedural Language Handler `_. diff --git a/docs/data-rw/postgresql/postgis/index.rst b/docs/data-rw/postgresql/postgis/index.rst index b9f3fbff..b6f82085 100644 --- a/docs/data-rw/postgresql/postgis/index.rst +++ b/docs/data-rw/postgresql/postgis/index.rst @@ -1,29 +1,28 @@ PostGIS ======= -`PostGIS `_ ist eine Erweiterung für PostgreSQL, die -geografische Objekte und Funktionen umfasst. Die Erweiterung implementiert u.a. -die `Simple-Feature-Access `_-Spezifikation -des `Open Geospatial Consortium `_. Obwohl PostgreSQL -bereits Geometrietypen unterstützt, sind diese jedoch für geographische Aufgaben -ungenügend. Daher erstellt PostGIS eigene Datentypen, die besser für -geographische Aufgaben geeignet sind. Im Einzelnen werden folgende -Geometrietypen unterstützt: +`PostGIS `_ is an extension for PostgreSQL that includes +geographic objects and functions. The extension implements i.a. the `Simple +Feature Access `_ specification of the `Open +Geospatial Consortium `_. Although PostgreSQL already +supports geometry types, these are insufficient for geographic tasks. Therefore, +PostGIS creates its own data types that are better suited for geographic tasks. +The following geometry types are supported: -* OpenGIS mit Well-Known Text und Well-Known Binary -* Extended Well-Known Text und Extended Well-Known Binary zusätzlich mit - Höheninformationen und/oder Messwerten -* SQL/MM mit Circularstring, Compoundcurve, Curvepolygon, Multicurve und +* OpenGIS with well-known text and well-known binary +* Extended Well-Known Text and Extended Well-Known Binary also with height + information and/or measured values +* SQL/MM with Circularstring, Compoundcurve, Curvepolygon, Multicurve und Multisurface -`GEOS `_ hingegen enthält die zahlreichen -räumlichen Funktionen und Operatoren für geographische Daten. +`GEOS `_, on the other hand, contains the numerous +spatial functions and operators for geographic data. -`pgRouting `_ schließlich enthält Routing-Funktionen -auf Basis von PostGIS. +Finally, `pgRouting `_ contains routing functions based +on PostGIS. -Im `OpenStreetMap `_-Projekt wird PostGIS zum -Rendern von Karten mit `Mapnik `_ verwendet. +In the `OpenStreetMap `_ project, PostGIS is +used to render maps with `Mapnik `_. .. toctree:: :hidden: diff --git a/docs/data-rw/postgresql/postgis/install.rst b/docs/data-rw/postgresql/postgis/install.rst index 3f3b60e8..a4b2f23f 100644 --- a/docs/data-rw/postgresql/postgis/install.rst +++ b/docs/data-rw/postgresql/postgis/install.rst @@ -1,43 +1,43 @@ -PostGIS installieren -==================== +Install PostGIS +=============== -Für Ubuntu 20.04 und 18.04 sowie Debian 10 könnt Ihr PostGIS einfach -installieren mit: +For Ubuntu 20.04 and 18.04 as well as Debian 10 you can simply install PostGIS +with: -code-block:: console +.. code-block:: console $ sudo apt install postgis postgresql-12-postgis-3 -Anschließend könnt Ihr PostGIS aktivieren. +Then you can activate PostGIS. -#. Wechseln zum PostgreSQL-User: +#. Switch to the PostgreSQL user: .. code-block:: console $ sudo -i -u postgres -#. Testuser und Datenbank erstellen: +#. Create test user and database: .. code-block:: console $ createuser postgis $ createdb postgis_db -O postgis -#. Verbindung zur Datenbank herstellen: +#. Establish a connection to the database: .. code-block:: console $ psql -d postgis_db psql (11.5 (Debian 11.5-3.pgdg100 + 1)) -#. Aktivieren der PostGIS-Erweiterung in der Datenbank: +#. Activate the PostGIS extension in the database: .. code-block:: console ppostgis_db = # CREATE EXTENSION postgis; CREATE EXTENSION -#. Überprüfen, ob PostGIS funktioniert: +#. Check that PostGIS is working: .. code-block:: console diff --git a/docs/data-rw/postgresql/postgis/load.rst b/docs/data-rw/postgresql/postgis/load.rst index 608dde44..8a134975 100644 --- a/docs/data-rw/postgresql/postgis/load.rst +++ b/docs/data-rw/postgresql/postgis/load.rst @@ -1,25 +1,25 @@ -Laden von Geodaten -================== +Loading geospatial data +======================= -Nun Laden wir einige Geodaten in unsere Datenbank, damit wir uns mit den Tools -und Prozessen zum Abrufen dieser Daten vertraut machen können. +Now let`s load some geospatial data into our database so that we can familiarise +ourselves with the tools and processes used to retrieve that data. -`Natural Earth `_ bietet eine großartige -Quelle für Basisdaten für die ganze Welt in verschiedenen Maßstäben. Und sas -Beste ist, dass diese Daten gemeinfrei sind: +`Natural Earth `_ provides a great source of +basic data for the whole world on various scales. And the best thing is that +this data is in the public domain: -#. Herunterladen der Daten +#. Download the data -.. code-block:: console + .. code-block:: console $ mkdir nedata $ cd !$ cd nedata $ wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/110m/cultural/ne_110m_admin_0_countries.zip -#. Entpacken der Datei +#. Unzip the file -.. code-block:: console + .. code-block:: console $ sudo apt install unzip $ unzip ne_110m_admin_0_countries.zip @@ -32,30 +32,29 @@ Beste ist, dass diese Daten gemeinfrei sind: inflating: ne_110m_admin_0_countries.shp inflating: ne_110m_admin_0_countries.shx -#. Laden in unsere ``postgis_db``-Datenbank +#. Load into our ``postgis_db`` database - Die Dateien ``.dbf``, ``.prj``, ``.shp`` und ``.shp`` bilden ein sog. - ShapeFile, ein beliebtes Geodaten-Datenformat, das von der GIS-Software - verwendet wird. Um dies in unsere Datenbank zu laden, benötigen wir - zusätzlich `GDAL `_, die *Geospatial Data Abstraction - Library*. Wenn wir GDAL installieren, erhalten wir auch OGR, *OpenGIS Simple - Features Reference Implementation*, eine Vektordaten-Übersetzungsbibliothek, - mit der wir das Shapefile in Daten übersetzen können. + The files ``.dbf``, ``.prj``, ``.shp`` and ``.shp`` form a so-called + ShapeFile, a popular geospatial data format that is used by GIS software. To + load this into our database, we also need `GDAL `_, the + *Geospatial Data Abstraction Library*. When we install GDAL we also get OGR, + *OpenGIS Simple Features Reference Implementation*, a vector data translation + library that we can use to translate the shapefile into data. - #. GDAL kann un einfach mit dem Paketmanager installiert werden: + #. GDAL can be easily installed with the package manager: .. code-block:: console $ sudo apt install gdal-bin - #. Anschließend wechseln wir in den ``postgresql``-User: + #. Then we switch to the ``postgresql`` user: .. code-block:: console $ sudo -i -u postgres - #. Nun konvertieren wir das Shapefile mit ``ogr2ogr`` und importieren es in - unsere Datenbank: + #. Now we convert the shapefile with ``ogr2ogr`` and import it into our + database: .. code-block:: console @@ -64,27 +63,27 @@ Beste ist, dass diese Daten gemeinfrei sind: /home/veit/nedata/ne_110m_admin_0_countries.shp ``-f PostgreSQL`` - gibt an, dass das Ziel eine PostgreSQL-Datenbank ist + iindicates that the target is a PostgreSQL database ``PG:dbname=postgis_db`` - gibt den PostgreSQL-Datenbanknamen an. - Neben dem Namen können so auch weitere Optionen angegeben werden, allgemein: + specifies the PostgreSQL database name. In addition to the name, other + options can also be specified, in general: .. code-block:: PG:"dbname='db_ename' host='addr' port='5432' user='x' password='y'" ``-progress`` - gibt einen Fortschrittsbalken aus + outputs a progress bar ``-nlt PROMOTE_TO_MULTI`` - gibt an, dass alle Objekttypen als Multipolygone in die Datenbank - geladen werden sollen + indicates that all object types should be loaded into the database as + multipolygons ``/home/veit/nedata/ne_110m_admin_0_countries.shp`` - gibt den Pfad zur Eingabedatei an + specifies the path to the input file .. seealso:: * `ogr2ogr `_ - #. Überprüfen des Imports mit ``ogrinfo`` + #. Check the import with ``ogrinfo`` .. code-block:: console @@ -98,7 +97,7 @@ Beste ist, dass diese Daten gemeinfrei sind: Feature Count: 177 … - #. Alternativ können wir uns auch einzelne Tabellen auflisten lassen: + #. Alternatively, we can also list individual tables: .. code-block:: console @@ -111,7 +110,7 @@ Beste ist, dass diese Daten gemeinfrei sind: public | spatial_ref_sys | table | postgres (2 rows) - #. Schließlich können wir uns bei der Datenbank abmelden mit + #. Finally, we can log out of the database with .. code-block:: console diff --git a/docs/data-rw/postgresql/postgis/optimising.rst b/docs/data-rw/postgresql/postgis/optimising.rst index 98998275..63450530 100644 --- a/docs/data-rw/postgresql/postgis/optimising.rst +++ b/docs/data-rw/postgresql/postgis/optimising.rst @@ -1,44 +1,44 @@ -Optimieren von PostgreSQL für GIS-Datenbankobjekte -================================================== +Optimising PostgreSQL for GIS database objects +============================================== -In der Standardinstallation ist PostgreSQL sehr zurückhaltend konfiguriert um -auf möglichst vielen Systemen lauffähig zu sein. GIS-Datenbankobjekte sind -jedoch im Vergleich zu Textdaten groß. Daher sollte PostgreSQL so konfiguriert -werden, dass sie mit diesen Objekten besser funktioniert. Hierfür konfigurieren -wir die Datei ``/etc/postgresql/9.3/main/postgresql.conf`` folgendermaßen: +In the standard installation, PostgreSQL is configured very cautiously so that +it can run on as many systems as possible. However, GIS database objects are +large compared to text data. Therefore, PostgreSQL should be configured to work +better with these objects. To do this, we configure the +``/etc/postgresql/9.3/main/postgresql.conf`` file as follows: -#. ``shared_buffer`` sollte auf ca. 75% des gesamten Arbeitsspeichers geändert - werden, jedoch 128 kB nie unterschreiten: +#. ``shared_buffer`` should be changed to approx. 75% of the total working + memory, but never fall below 128 kB: .. code-block:: shared_buffers = 768MB -#. ``work_mem`` sollte auf mindestens 16MB erhöht werden: +#. ``work_mem`` should be increased to at least 16MB: .. code-block:: work_mem = 16MB -#. ``maintenance_work_mem`` sollte auf 128MB erhöht werden: +#. ``maintenance_work_mem`` should be increased to 128MB: .. code-block:: maintenance_work_mem = 128MB -#. ``checkpoint_segments`` sollte auf ``6`` gesetzt werden: +#. ``checkpoint_segments`` should be set to ``6``: .. code-block:: checkpoint_segments = 6 -#. Schließlich sollte noch ``random_page_cost`` auf ``2.0`` gesetzt werden. +#. Finally, ``random_page_cost`` should be set to ``2.0``. .. code-block:: random_page_cost = 2.0 -Damit die Änderungen übernommen werden, sollte PostgreSQL neu gestartet werden: +PostgreSQL should be restarted for the changes to take effect: .. code-block:: console diff --git a/docs/data-rw/postgresql/psycopg2.rst b/docs/data-rw/postgresql/psycopg2.rst index 000ef142..4069e6fd 100644 --- a/docs/data-rw/postgresql/psycopg2.rst +++ b/docs/data-rw/postgresql/psycopg2.rst @@ -1,18 +1,18 @@ Psycopg ======= -`Pycopg `_ ist ein PostgreSQL-Adapter, der auf der -C-Bibliothek für PostgreSQL `libpq -`_ basiert. Er bietet u.a.: +`Pycopg `_ is a PostgreSQL adapter based on the C +library for PostgreSQL `libpq +`_. Among other things, it +offers: -* DB-API-2.0-rKkompatibilität -* Multithreading bei Thread Safety +* DB API 2.0 compatibility +* Multithreading with thread safety * `Connections pooling `_ - um einen Cache von bestehenden Datenbankverbindungen für Anfragen verwenden - zu können. + to be able to use a cache of existing database connections for queries. * `Asynchronous - `_ und + `_ and `Coroutines support `_ -* `Adaptation der Python Typen in SQL +* `Adaptation of the Python types in SQL `_ diff --git a/docs/data-rw/postgresql/sec.rst b/docs/data-rw/postgresql/sec.rst index 13fbb59d..76c6c576 100644 --- a/docs/data-rw/postgresql/sec.rst +++ b/docs/data-rw/postgresql/sec.rst @@ -1,16 +1,14 @@ -Datenbank-Sicherheit -==================== +Database security +================= -Datenbank-Berechtigungen ------------------------- +Database permissions +-------------------- -Das PostgreSQL-Login per Superuser ``postgres`` sollte immer nur über -Unix-Domain-Sockets und über ``localhost`` erlaubt sein. Der Zugang mit -`Peer-Authentifizierung -`_ in der -`pg_hba.conf -`_-Datei kann -hingegen gewährt werden: +The PostgreSQL login via superuser ``postgres`` should only ever be allowed via +Unix domain sockets and via ``localhost``. Access with `peer authentication +`_ in the +`pg_hba.conf `_, +however, can be granted: .. code-block:: @@ -18,34 +16,33 @@ hingegen gewährt werden: local all postgres peer host all all 10.23.42.1/24 scram-sha-256 -Die Datenbank sollte vom Datenbankadministrator angelegt und anschließend so -konfiguriert werden, dass sich nicht jeder ``(PUBLIC)`` damit verbinden kann: +The database should be created by the database administrator and then configured +in such a way that not everyone ``(PUBLIC)`` can connect to it: .. code-block:: postgresql CREATE DATABASE myapp; REVOKE ALL ON myapp FROM PUBLIC; -Damit kann sich nur noch der Superuser mit der Datenbank ``myapp`` verbinden. +This means that only the superuser can connect to the ``myapp`` database. -Passwörter speichern --------------------- +Save passwords +-------------- -Passwörter sollten niemals im Klartext, also z.B. auch nicht in einer -``.env``-Datei gespeichert werden. Beim Speichern und Übermitteln von -Passwörtern sollte dies immer mit `Salts -`_ versehen sein. Für -PostgreSQL gibt es hierfür die Erweiterung `pgcrypto -`_, die -einfach aktiviert werden kann mit +Passwords should never be in plain text, e.g. also not be saved in an ``.env`` +file. When saving and transmitting passwords, this should always be `salted +`_. For PostgreSQL there is +the extension `pgcrypto +`_, which can be +easily activated with .. code-block:: postgresql CREATE EXTENSION pgcrypto; -Daher sollten bereits beim Anlegen sichere Passwörter vergeben werden, die -anschließend z.B. in `Vault `_ o.ä. -gespeichert werden: +For this reason, secure passwords should be assigned when they are created, +which can then get saved e.g. in `Vault `_ or +similar: .. code-block:: postgresql @@ -53,9 +50,8 @@ gespeichert werden: CREATE USER myapp_reader IN ROLE users PASSWORD '…'; CREATE USER myapp_writer IN ROLE users PASSWORD '…'; -Anschließend erhalten dann User mit der Rolle ``myapp_users`` zunächst -``CONNECT``-Rechte und dann ``myapp_reader`` Leserechte und ``myapp_writer`` -Schreibrechte: +Then users with the role ``myapp_users`` first get ``CONNECT`` rights and then + ``myapp_reader`` read rights and ``myapp_writer`` write rights: .. code-block:: postgresql @@ -63,8 +59,8 @@ Schreibrechte: GRANT SELECT ON diagnosis_key TO myapp_reader; GRANT INSERT ON diagnosis_key TO myapp_writer; -Der User ``myapp_reader`` kann damit jedoch alle Daten auf einmal lesen. Auch -dies ist ein Angriffspunkt, der besser durch eine Funktion beschnitten wird: +The user ``myapp_reader`` can, however, read all data at once. This is also a +point of attack that is better cut by a function: .. code-block:: postgresql @@ -73,9 +69,9 @@ dies ist ein Angriffspunkt, der besser durch eine Funktion beschnitten wird: AS 'SELECT key_data FROM diagnosis_key WHERE id = in_id;' LANGUAGE sql SECURITY DEFINER SET search_path = :schema, pg_temp; -Anschließend wird die Funktion ``myapp_owner`` zugewiesen, ``myapp_reader`` und -``myapp_writer`` die Berechtigungen entzogen und schließlich die Ausführung der -Funktion ``myapp_reader`` erlaubt: +Then the function ``myapp_owner`` is assigned, the authorisations for +``myapp_reader`` and ``myapp_writer`` are revoked and finally the execution of +the function ``myapp_reader`` is allowed: .. code-block:: postgresql @@ -83,18 +79,17 @@ Funktion ``myapp_reader`` erlaubt: REVOKE ALL ON FUNCTION get_key_dataUUID) FROM PUBLIC; GRANT EXECUTE ON FUNCTION get_key_data(UUID) TO myapp_reader; -Damit kann ``myapp_reader`` also nur noch einen einzelnen Datensatz lesen. +This means that ``myapp_reader`` can only read a single data record. id -- -Die ``id`` sollte nicht als ``serial``, ``bigserial`` o.ä. realisiert werden. -Hochzählende Zahlen könnten von Angreifern leicht erraten werden. Daher ist der -UUIDv4-Datentyp deutlich besser geeignet. In PostgreSQL könnt Ihr UUIDv4 -generieren mit der `uuid-ossp -`_-Erweiterung oder für -PostgreSQL≥9.4 auch der `pgcrypto -`_-Erweiterung: +The ``id`` shouldn`t be written as ``serial``, ``bigserial`` or similar. +Counting numbers could be easily guessed by attackers. Therefore the UUIDv4 data +type is much more suitable. In PostgreSQL you can generate UUIDv4 with the +`uuid-ossp `_ extension +or for PostgreSQL≥9.4 also the `pgcrypto +`_ extension: .. code-block:: postgresql @@ -104,7 +99,7 @@ PostgreSQL≥9.4 auch der `pgcrypto … ); -oder +or .. code-block:: postgresql @@ -114,28 +109,27 @@ oder … ); -Zeitstempel ------------ +Time stamp +---------- -Gelegentlich werden Datum und Zeit als ``bigint``, also als Zahl, gespeichert, -und dies obwohl es auch einen ``TIMESTAMP``-Datentyp gibt. Dies hätte den -Vorteil, dass dann auch einfach mit ihnen gerechnet werden kann, also z.B.: +Occasionally, the date and time are stored as ``bigint``, i.e. as a number, even +though there is also a ``TIMESTAMP`` data type. This would have the advantage +that you can easily count on them, for example: .. code-block:: postgresql SELECT age(submission_timestamp); SELECT submission_timestamp - '1 day'::interval; -Außerdem könnten die Daten nach einer bestimmten Zeit gelöscht werden, z.B. nach -dreißig Tagen mit: +In addition, the data could be deleted after a certain period of time, e.g. +after thirty days with: .. code-block:: postgresql DELETE FROM diagnosis_key WHERE age(submission_timestamp) > 30; -Das Löschen kann noch beschleunigt werden, wenn für jeden Tag mit der -PostgreSQL-Erweiterung `pg_partman `_ eine eigene -`Partition `_ erstellt wird. +Deletion can be accelerated if a separate partition is created for each day with +the PostgreSQL extension `pg_partman `_. .. seealso:: * `PostgreSQL Secure Monitoring (Posemo) diff --git a/docs/data-rw/postgresql/sqlalchemy.rst b/docs/data-rw/postgresql/sqlalchemy.rst index 4a27427f..9c277c24 100644 --- a/docs/data-rw/postgresql/sqlalchemy.rst +++ b/docs/data-rw/postgresql/sqlalchemy.rst @@ -1,19 +1,19 @@ SQLAlchemy ========== -`SQLAlchemy `_ ist ein Python-SQL-Toolit und -objektrelationaler Mapper. +`SQLAlchemy `_ is a Python-SQL-Toolkit and +object-relational mapper. -SQLAlchemy ist bekannt für sein ORM, wobei es verschiedene Muster für das -objektrelationale Mapping bereitstellt, wobei Klassen auf verschiedene Weise auf -die Datenbank abgebildet werden können. Das Objektmodell und das Datenbankschema -sind von Anfang an sauber entkoppelt. +SQLAlchemy is known for its ORM, whereby it provides different patterns for +object-relational mapping, whereby classes can be mapped to the database in +different ways. The object model and the database schema are cleanly decoupled +from the start. -SQLAlchemy unterscheidet sich grundlegend von anderen ORMs, da SQL und Details -der Objekt-Relation nicht wegabstrahiert werden: alle Prozesse werden als eine -Zusammenstellung einzelner Tools dargestellt. +SQLAlchemy differs fundamentally from other ORMs, as SQL and details of the +object relation are not abstracted away: all processes are represented as a +collection of individual tools. -Datenbankverbindung +Database connection ------------------- :: @@ -21,8 +21,8 @@ Datenbankverbindung from sqlalchemy import create_engine engine = create_engine('postgresql:///example', echo=True) -Datenmodell ------------ +Data model +---------- :: @@ -51,8 +51,8 @@ Datenmodell address_id = Column(Integer, ForeignKey(Address.id), nullable=False) address = relationship('Address') -Tabellen erstellen ------------------- +Create tables +------------- :: diff --git a/docs/data-rw/requests/index.rst b/docs/data-rw/requests/index.rst index b121b422..81d8c686 100644 --- a/docs/data-rw/requests/index.rst +++ b/docs/data-rw/requests/index.rst @@ -1,9 +1,9 @@ Requests ======== -`Requests `_ vereinfacht HTML-Anfragen -gegenüber der Python-Standardbibliothek -`urllib.request `_. +`Requests `_ simplifies HTML requests +compared to the Python standard library `urllib.request +`_. .. toctree:: :hidden: diff --git a/docs/data-rw/requests/module.ipynb b/docs/data-rw/requests/module.ipynb index e418c8b5..185e39fc 100644 --- a/docs/data-rw/requests/module.ipynb +++ b/docs/data-rw/requests/module.ipynb @@ -4,13 +4,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Modul erstellen\n", + "# Create module\n", "\n", - "Es ist nicht sehr praktisch, Jupyter jedes Mal zu starten und alle Zellen des [request-Notebooks](requests.html) zu durchlaufen, nur um die Funktionen verwenden zu können. Stattdessen sollten wir unsere Funktionen in einem separaten Modul speichern, wie in [nominatim.py](nominatim.py):\n", + "It is not very practical to start Jupyter every time and go through all the cells of the [request notebook](requests.rst) just to be able to use the functions. Instead, we should store our functions in a separate module, like in [nominatim.py](nominatim.py):\n", "\n", - "1. Hierfür habe ich in Jupyter an derselben Stelle, wie diese Notebooks eine neue Textdatei erstellt, ihr den Namen `nominatim.py` gegeben.\n", - "2. Anschließend habe ich die Importe, die Methode `nominatim_search` und deren Decorator `lru_cache` hineinkopiert und die Datei gespeichert.\n", - "3. Nun können wir zu unserem Notebook zurückkehren und den Code aus dieser Datei importieren und unsere Suchen ausführen:" + "1. For this I have created a new text file in Jupyter in the same place as these notebooks, and named it `nominatim.py`.\n", + "2. Then I copied the imports, the method `nominatim_search` and its decorator `lru_cache` and saved the file.\n", + "3. Now we can go back to our notebook and import the code from this file and do our searches:" ] }, { @@ -87,9 +87,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Auslagern des Codes von Notebooks in Module erleichtert nicht nur dessen Wiederverwendbarkeit, es macht auch die Notebooks lesbarer.\n", + "The outsourcing of the notebook’s code to modules makes it easier to reuse it, and also makes the notebooks more readable.\n", "\n", - "Damit der Code jedoch funktioniert, muss sich geocode.py im selben Ordner wie ein Jupyter-Notizbuch befinden. Wenn Sie dieses Modul von einer anderen Stelle aus aufrufen möchten, müsste die Pfadangabe im `import`geändert werden. In diesem Fall sollte besser ein eigenes Paket erstellt werden, wie dies in [Packetierung](../productive/packaging/index.html) beschrieben ist." + "However, for the code to work, geocode.py needs to be in the same folder as a Jupyter notebook. If you want to call this module from another location, the path specification in the import would have to be changed. In this case it is better to create your own package, as described in [Packing](../../productive/packaging/index.rst)." ] } ], diff --git a/docs/data-rw/requests/requests.ipynb b/docs/data-rw/requests/requests.ipynb index 26f0300e..a8ff9c73 100644 --- a/docs/data-rw/requests/requests.ipynb +++ b/docs/data-rw/requests/requests.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Requests Installation und Beispielanwendung" + "# Requests installation and sample application" ] }, { @@ -13,14 +13,14 @@ "source": [ "## Installation\n", "\n", - "Für die Kommunikation mit solchen REST-APIs ist die [requests](https://requests.readthedocs.io/)-Bibliothek hilfreich. Mit [Spack](https://jupyter-tutorial.readthedocs.io/de/latest/productive/envs/spack/index.html) könnt ihr requests in eurem Kernel bereitstellen:\n", + "The requests library is useful for communicating with REST APIs. With [Spack](../../productive/envs/spack/index.rst) you can provide requests in your kernel:\n", "\n", "``` bash\n", "$ spack env activate python-374\n", "$ spack install py-requests ^python@3.7.4%gcc@9.1.0\n", "```\n", "\n", - "Alternativ könnt ihr requests auch mit anderen Paketmanagern installieren, z.B.\n", + "Alternatively, you can install requests with other package managers, e.g.\n", "\n", "``` bash\n", "$ pipenv install requests\n", @@ -31,19 +31,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiel OSM Nomination API\n", + "## Example OSM Nomination API\n", "\n", - "In diesem Beispiel holen wir unsere Daten von der [OpenStreetMap Nomination API](https://nominatim.org/release-docs/develop/api/Overview/#nominatim-api). Diese ist erreichbar über die URL `https://nominatim.openstreetmap.org/search?`. Um z.B. Informationen über das Berlin Congress Center in Berlin im JSON-Format zu erhalten, sollte die URL `https://nominatim.openstreetmap.org/search.php?q=Alexanderplatz+Berlin&format=json` angegeben werden, und wenn ihr euch den entsprechenden Kartenausschnitt anzeigen\n", - "lassen wollt, so müsst ihr einfach nur `&format=json` weglassen\n", + "In this example we get our data from the [OpenStreetMap Nomination API](https://nominatim.org/release-docs/develop/api/Overview/#nominatim-api). This can be reached via the URL `https://nominatim.openstreetmap.org/search?`. To e.g. receive information about the Berlin Congress Center in Berlin in JSON format, the URL `https://nominatim.openstreetmap.org/search.php?q=Alexanderplatz+Berlin&format=json` should be given, and if you want to display the corresponding map section you just have to leave out `&format=json`.\n", "\n", - "Anschließend definieren wir die Basis-URL und die Parameter. Nominatim erwartet mindestens die folgenden beiden Parameter\n", + "Then we define the base URL and the parameters. Nominatim expects at least the following two parameters\n", "\n", - "| Schlüssel | Werte |\n", + "| Key | Value |\n", "| --------- | ------------------------------------ |\n", - "| `q` | Adressabfrage, die folgende Spezifikationen erlaubt: `street`, `city`, `county`, `state`, `country` und `postalcode`. |\n", - "| `format` | Format, in dem die Daten zurückgegeben werden. Möglich Werte sind `html`, `xml`, `json`, `jsonv2`, `geojson` und `geocodejson`. |\n", + "| `q` | Address query that allows the following specifications: `street`, `city`, `county`, `state`, `country` and `postalcode`. |\n", + "| `format` | Format in which the data is returned. Possible values are `html`, `xml`, `json`, `jsonv2`, `geojson` and `geocodejson`. |\n", "\n", - "Die Abfrage kann dann gestellt werden mit:" + "The query can then be made with:" ] }, { @@ -142,7 +141,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Es werden drei verschiedene Orte gefunden, der Platz, eine Bushaltestelle und ein Hotel. Um nun weiter filtern zu können, können wir uns nur den bedeutendsten Ort anzeigen lassen:" + "Three different locations are found, the square, a bus stop and a hotel. In order to be able to filter further, we can only display the most important location:" ] }, { @@ -192,14 +191,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Nachdem wir nun wissen, dass der Code funktioniert, wollen wir alles in eine saubere und flexible Funktion umwandeln. " + "Now that we know the code works, let’s turn everything into a clean and flexible function." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Um sicherzustellen, dass die Interaktion erfolgreich war, verwenden wir die Methode `raise_for_status` von `requests`, die eine Exception auslöst, wenn der HTTP-Statuscode nicht `200 OK` ist:" + "To ensure that the interaction was successful, we use the `raise_for_status` method of `requests`, which throws an exception if the HTTP status code isn’t `200 OK`:" ] }, { @@ -215,7 +214,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Da wir die Lastgrenzen der Nomination-API nicht überschreiten möchten, werden wir unsere Anforderungen mit der Funktion `time.sleep` verzögern:" + "Since we don't want to exceed the load limits of the Nomination API, we will delay our requests with the `time.sleep` function:" ] }, { @@ -255,7 +254,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Als nächstes deklarieren wir die Funktion selbst. Als Argumente benötigen wir die Adresse, das Format, das Limit der zurückzugebenden Objekte mit dem Standardwert `1` und weitere `kwargs` (**k**ey**w**ord **arg**ument**s**), die als Parameter übergeben werden:" + "Next we declare the function itself. As arguments we need the address, the format, the limit of the objects to be returned with the default value `1` and further `kwargs` (**k**ey**w**ord **arg**ument**s**) that are passed as parameters:" ] }, { @@ -283,7 +282,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Nun können wir die Funktion ausprobieren, z.B. mit" + "Now we can try out the function, e.g. with" ] }, { @@ -320,7 +319,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Ihr könnt jedoch neben `address` noch weitere Parameter verwenden. Eine Übersicht erhaltet ihr in den [Nominatim Docs](https://nominatim.org/release-docs/develop/api/Search/#parameters)." + "However, you can use other parameters besides `address`. You can get an overview in the [Nominatim Docs](https://nominatim.org/release-docs/develop/api/Search/#parameters)." ] }, { @@ -360,7 +359,7 @@ "source": [ "## Caching\n", "\n", - "Falls innerhalb einer Session immer wieder dieselben Abfragen gestellt werden sollen,ist es sinnvoll, diese Daten nur einmal abzurufen und wiederzuverwenden. In Python können wir `lru_cache` aus der `functools`-Standardbibliothek von Python verwenden. `lru_cache` speichert die N letzten Anfragen (**L**east **R**ecent **U**sed) und sobald das Limit überschritten wird, werden die ältesten Werte verworfen. Um dies für die Methode `nominatim_search` zu verwenden, müsst ihr lediglich einen Import und einen *Decorator* defnieren:" + "If the same queries are to be asked over and over again within a session, it makes sense to call up this data only once and use it again. In Python we can use `lru_cache` from Python’s standard `functools` library. `lru_cache` saves the last `N` requests (**L**east **R**ecent **U**sed) and as soon as the limit is exceeded, the oldest values are discarded. To use this for the `nominatim_search` method, all you have to do is define an import and a decorator:" ] }, { @@ -381,7 +380,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`lru_cache` speichert die Ergebnisse jedoch nur während einer Session. Wenn ein Skript wegen einem Timeout oder einer Exception beendet wird, sind die Ergebnisse verloren. Sollen die Daten dauerhafter gespeichert werden, können Tools wie [joblib](https://joblib.readthedocs.io/) oder [python-diskcache](http://www.grantjenks.com/docs/diskcache/) verwendet werden." + "However, `lru_cache` only saves the results during a session. If a script terminates because of a timeout or an exception, the results are lost. If the data is to be saved more permanently, tools such as [joblib](https://joblib.readthedocs.io/) or [python-diskcache](http://www.grantjenks.com/docs/diskcache/) can be used." ] } ], diff --git a/docs/first-steps/create-notebook.rst b/docs/first-steps/create-notebook.rst index c6f385c0..358bcb99 100644 --- a/docs/first-steps/create-notebook.rst +++ b/docs/first-steps/create-notebook.rst @@ -1,63 +1,61 @@ -Notebook erstellen -================== +Create notebook +=============== -Nachdem der Notebook-Server gestartet wurde, können wir unser erstes Notebook -erstellen. +After the notebook server has started, we can create our first notebook. -Erstellen eines Notebooks -------------------------- +Create a notebook +----------------- -In eurem Standard-Browser solltet ihr das Notebook-Dashboard mit dem Menü *New* -auf der rechten Seite sehen. In diesem Menü werden alle Notebook-Kernel -aufgeführt, initial jedoch vermutlich nur *Python 3*. +In your standard browser you should see the notebook dashboard with the *New* +menu on the right. All notebook kernels are listed in this menu, but initially +probably only *Python 3*. -Nachdem ihr :menuselection:`New --> Python 3` ausgewählt habt, wird ein neues -Notebook ``Untitled.ipynb`` erstellt und in einem neuen Reiter angezeigt: +After you have selected :menuselection:`New --> Python 3`, a new notebook + ``Untitled.ipynb`` will be created and displayed in a new tab: .. image:: initial-notebook.png -Umbenennen des Notebooks ------------------------- +Renaming the notebook +--------------------- -Als nächstes solltet Ihr dieses Notebook umbenennen indem ihr auf den Titel -*Untitled* klickt: +Next you should rename this notebook by clicking on the title *Untitled*: .. image:: rename-notebook.png -Die Notebook-Oberfläche ------------------------ +The notebook user interface +--------------------------- -Es gibt zwei wichtige Begriffe, um Jupyter Notebooks zu beschreiben: *Zelle* und -*Kernel*: +There are two important terms used to describe Jupyter Notebooks: *cell* and +*kernel*: .. glossary:: - *Notebook-Kernel* - *Rechenmaschine*, die den in einem Notebook enthaltenen Code ausführt. + *Notebook kernel* + *Computational engine* that executes the code contained in a notebook. - *Notebook-Zelle* - Container für Text, der in einem Notebook angezeigt werden soll oder für - Code, der vom Kernel des Notebooks ausgeführt werden soll. + *Notebook cell* + Container for text to be displayed in a notebook or for code to be + executed by the notebook’s kernel. *Code* - enthält Code, der im Kernel ausgeführt werden soll und dessen Ausgabe - unterhalb angezeigt wird. + contains code to be executed in the kernel, and the output which is + shown below. *Markdown* - enthält mit `Markdown - `_ formatierten - Text, der interpretiert wird sobald :menuselection:`Run` gedrückt wird. + contains text formatted with `Markdown + `_, which is + interpreted as soon as :menuselection:`Run` is pressed. -.. _was-ist-eine-ipynb-datei: +.. _whats-an-ipynb-file: -Was ist eine ``ipynb``-Datei? ------------------------------- +What’s an ``ipynb`` file? +------------------------- -Diese Datei beschreibt ein Notebook im `JSON -`_-Format. Jede Zelle -und ihr Inhalt einschließlich Bildern werden dort zusammen mit einigen Metadaten -aufgelistet. Ihr könnt euch diese anschauen wenn ihr im Dashboard das Notebook -auswählt und dann auf :menuselection:`edit` klickt. So sieht z.B. die JSON-Datei -für `my-first-notebook.ipynb `_ folgendermaßen aus: +This file describes a notebook in `JSON `_ +format. Each cell and its contents including pictures are listed there along +with some metadata. You can have a look at them if you select the notebook in +the dashboard and then click on :menuselection:`edit`. E.g. the JSON file for +`my-first-notebook.ipynb `_ +looks like this: .. code-block:: json @@ -111,35 +109,30 @@ für `my-first-notebook.ipynb `_ folgendermaßen aus: "nbformat_minor": 2 } -Speichern und Checkpoints -------------------------- - -Beim Klick auf :menuselection:`Save and Checkpoint` wird eure ``ipynb``-Datei -gespeichert. Aber was hat es mit dem *Checkpoint* auf sich? - -Jedesmal, wenn ihr ein neues Notebook anlegt, wird auch eine Datei angelegt, -die üblicherweise alle 120 Sekunden automatisch eure Änderungen speichert. -Dieser Checkpoint findet sich üblicherweise in einem versteckten Verzeichnis -namens ``.ipynb_checkpoints/``. Diese Checkpoint-Datei ermöglicht euch daher, -eure nicht gespeicherten Daten im Falle eines unerwarteten Problems -wiederherzustellen. Ihr könnt in :menuselection:`File --> Revert to Checkpoint` -zu einer der letzten Checkpoints zurückgehen. - -Tipps & Tricks --------------- - -#. Gebt dem Notebook einen Titel (``# My title``) und ein aussagekräftiges - Vorwort um den Inhalt und Zweck des Notebooks zu beschreiben. -#. Erstellt Überschriften und Dokumentationen in Markdown-Zellen um euer - Notebook zu strukturieren und eure Workflow-Schritte zu erläutern. Dabei ist - vollkommen egal, ob ihr das für eure Kollegen oder für euer zukünftig selbst - macht. -#. Verwendet *Table of Contents (2)* aus der - :doc:`/workspace/jupyter/nbextensions/list`, um ein Inhaltsverzeichnis - zu erstellen. -#. Verwendet die Notebook-Erweiterung :ref:`setup +Save and checkpoints +-------------------- + +When you click on :menuselection:`Save and Checkpoint`, your ``ipynb`` file will +be saved. But what is the checkpoint all about? + +Every time you create a new notebook, a file is also created, which usually +automatically saves your changes every 120 seconds. This checkpoint is usually +located in a hidden directory called ``.ipynb_checkpoints/``. This checkpoint +file therefore enables you to restore your unsaved data in the event of an +unexpected problem. You can go back to one of the last checkpoints in +:menuselection:`File --> Revert to Checkpoint`. + +Tips and tricks +--------------- + +#. Give the notebook a title (``# My title``) and a meaningful foreword to + describe the content and purpose of the notebook. +#. Create headings and documentation in Markdown cells to structure your + notebook and explain your workflow steps. It doesn’t matter whether you do + this for your colleagues or for yourself in the future. +#. Use *Table of Contents (2)* from the + :doc:`/workspace/jupyter/nbextensions/list` to create a table of contents. +#. Use the notebook extension :ref:`setup `. -#. Verwendet *Snippets* aus der - :doc:`/workspace/jupyter/nbextensions/list`, um weitere, häufig - benötigte Code-Blöcke, z.B. typische Importanweisungen, bequem einfügen zu - können. +#. Use snippets from the list of extensions to add more frequently used code + blocks, e.g. typical import instructions, easy to insert. diff --git a/docs/first-steps/example.ipynb b/docs/first-steps/example.ipynb index 9eb9379a..01db91db 100644 --- a/docs/first-steps/example.ipynb +++ b/docs/first-steps/example.ipynb @@ -4,14 +4,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Beispiel" + "# Example" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Üblicherweise werden zunächst die erforderlichen Bibliotheken importiert:" + "Usually the required libraries are imported first:" ] }, { @@ -28,9 +28,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispieldaten herunterladen\n", + "## Download sample data\n", "\n", - "Anschließend laden wir die Beispieldaten herunter. Hierfür können wir innerhalb von iPython Shell-Befehle verwenden, indem wir ``!`` voranstellen. " + "Then we download the sample data. We can use shell commands within iPython for this by prefixing ``!``." ] }, { @@ -56,9 +56,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispieldaten einlesen\n", + "## Read in sample data\n", "\n", - "Anschließend lesen wir die csv-Daten in Pandas als DataFrame ein:" + "Then we read the csv data into pandas as a DataFrame:" ] }, { @@ -74,7 +74,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Daten untersuchen" + "## Examine data" ] }, { @@ -280,9 +280,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Umbenennen der Spalten\n", + "### Renaming the columns\n", "\n", - "Dies erleichtert uns später, auf die Spalten zu verweisen:" + "This will make it easier for us to refer to the columns later:" ] }, { @@ -386,7 +386,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Überprüfen der Anzahl der Datensätze" + "### Check the number of records" ] }, { @@ -413,14 +413,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das entspricht 500 Zeilen pro Jahr von 1955 bis einschließlich 2005." + "This corresponds to 500 lines per year from 1955 up to 2005." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Überprüfen der Datentypen" + "### Check the data types" ] }, { @@ -452,7 +452,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die Spalte `profit` sollte vom Datentyp `float64` sein; das ist hier nicht der Fall. Dies weist darauf hin, dass die Spalte wahrscheinlich einige Werte enthält, die keine Zahlen sind. Überprüfen wir dies mit einem regulären Ausdruck:" + "The column `profit` should be of the data type` float64`; that is not the case here. This indicates that the column is likely to have some values that are not numbers. Let's check this with a regular expression:" ] }, { @@ -557,7 +557,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Ob es neben `N.A.` noch andere nichtnumerische Werte gibt, überprüfen wir mit" + "We also check whether there are other non-numerical values besides `N.A.`:" ] }, { @@ -584,7 +584,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Als nächstes untersuchen wir, wie viele Datensätze davon betroffen sind:" + "Next, let’s examine how many records are affected:" ] }, { @@ -611,7 +611,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "… und wie sie sich über die Jahre verteilen:" + "… and how they are distributed over the years:" ] }, { @@ -640,7 +640,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Hier können wir sehen, dass die problematischen Datenpunkte in einem Jahr 24 nicht überschreiten und bei 500 Datenpunkte pro Jahr würde das Entfernen dieser Werte weniger als 5% der Daten für dieses Jahr ausmachen. Nehmen wir an, dass es für uns akzeptabel ist, dass die problematischen Daten entfernt werden können:" + "Here we can see that the problematic data points will not exceed 24 in a year, and with 500 data points per year, removing these values would be less than 5% of the data for that year. Let’s assume that it is acceptable to us that the problematic data can be removed:" ] }, { @@ -657,7 +657,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir sollten nun `25500 - 369` Datensätze haben:" + "We should now have `25500 - 369` records:" ] }, { @@ -684,7 +684,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "… und für die Spalte `profit` sollte der Datentyp nun `float64` sein:" + "… and for the column `profit` the data type should now be` float64`:" ] }, { diff --git a/docs/first-steps/index.rst b/docs/first-steps/index.rst index 55d56ae7..f46db842 100644 --- a/docs/first-steps/index.rst +++ b/docs/first-steps/index.rst @@ -1,6 +1,6 @@ -============== -Erste Schritte -============== +=========== +First steps +=========== .. toctree:: :hidden: diff --git a/docs/first-steps/install.rst b/docs/first-steps/install.rst index b34a4f2c..9a73c5ad 100644 --- a/docs/first-steps/install.rst +++ b/docs/first-steps/install.rst @@ -1,17 +1,16 @@ -Jupyter Notebook installieren -============================= +Install Jupyter Notebook +======================== .. _pipenv-installieren: -Pipenv installieren -------------------- +Install Pipenv +-------------- -:term:`pipenv` ist ein Abhängigkeitsmanager für Python-Projekte. Er nutzt -:term:`Pip` zum Installieren von Python-Paketen, er vereinfacht jedoch die -Verwaltung von Abhängigkeiten. Pip kann zum Installieren von Pipenv verwendet -werden, es sollte jedoch das ``--user``-Flag verwendet werden, damit es nur -für diesen Nutzer bereitsteht. Dadurch soll verhindert werden, dass -versehentlich systemweite Pakete überschrieben werden: +:term:`pipenv` is a dependency manager for Python projects. It uses Pip to +install Python packages, but it simplifies dependency management. Pip can be +used to install Pipenv, but the ``--user`` flag should be used so that it is +only available to that user. This is to prevent system-wide packets from +being accidentally overwritten: .. code-block:: console @@ -25,46 +24,45 @@ versehentlich systemweite Pakete überschrieben werden: .. note:: - Wenn Pipenv nach der Installation nicht in der Shell verfügbar ist, muss - ggf. das ``USER_BASE/bin``-Verzeichnis in ``PATH`` angegeben werden. + If Pipenv is not available in the shell after installation, the + ``USER_BASE/bin`` directory may have to be specified in ``PATH``. - * Unter Linux und MacOS lässt sich ``USER_BASE`` ermitteln mit: + Under Linux and MacOS, ``USER_BASE`` can be determined with: - .. code-block:: console + .. code-block:: console $ python3 -m site --user-base /home/veit/.local - Anschließend muss noch das ``bin``-Verzeichnis angehängt und zu ``PATH`` - hinzugefügt werden. Alternativ kann ``PATH`` dauerhaft gesetzt werden, indem - ``~/.profile`` oder ``~/.bash_profile`` geändert werden, in meinem Fall also: + Then the ``bin`` directory has to be appended and added to the ``PATH``. + Alternatively, ``PATH`` can be set permanently by changing ``~/.profile`` or + ``~/.bash_profile``, in my case: - .. code-block:: bash + .. code-block:: bash export PATH=/home/veit/.local/bin:$PATH - * Unter Windows kann das Verzeichnis ermittelt werden mit - ``py -m site --user-site`` und anschließend ``site-packages`` durch - ``Scripts`` ersetzt werden. Dies ergibt dann z.B.: + * Under Windows, the directory can be determined with + ``py -m site --user-site`` and then ``site-packages`` can be replaced by + `` Scripts``. This then results in, for example: - .. code-block:: console + .. code-block:: console C:\Users\veit\AppData\Roaming\Python36\Scripts - Um dauerhaft zur Verfügung zu stehen, kann dieser Pfad unter ``PATH`` - im Control Panel eingetragen werden. + In order to be permanently available, this path can be entered under + ``PATH`` in the control panel. -Weitere Informationen zur nutzerspezifischen Installation findet ihr in `User +Further information on user-specific installation can be found in `User Installs `_. -Virtuelle Umgebung mit ``jupyter`` erstellen --------------------------------------------- +Create a virtual environment with ``jupyter`` +--------------------------------------------- -:term:`Virtuelle Python-Umgebungen ` ermöglichen die -Installation von Python-Paketen an einem isolierten Ort für eine bestimmte -Anwendung, anstatt sie global zu installieren. Ihr habt also eure eigenen -Installationsverzeichnisse und teilt keine Bibliotheken mit anderen -virtuellen Umgebungen: +`Python virtual environments ` allow Python packages to be +installed in an isolated location for a specific application, rather than +installing them globally. So you have your own installation directories and do +not share libraries with other virtual environments: .. code-block:: console @@ -79,8 +77,8 @@ virtuellen Umgebungen: Installing jupyter... ... -``jupyter notebook`` starten ----------------------------- +Start ``jupyter notebook`` +-------------------------- .. code-block:: console @@ -96,11 +94,11 @@ virtuellen Umgebungen: Or copy and paste one of these URLs: http://localhost:8888/?token=53abd45a3002329de77f66886e4ca02539d664c2f5e6072e -Daraufhin wird euer Standard-Webbrowser mit dieser URL geöffnet. +Your standard web browser will then open with this URL. -Wenn das Notebook in eurem Browser geöffnet wird, wird das Notebook-Dashboard -mit einer Liste der Notebooks, Dateien und Unterverzeichnisse in dem Verzeichnis -angezeigt, in dem der Notebook-Server gestartet wurde. In den meisten Fällen möchtet -ihr einen Notebook-Server in eurem Projektverzeichnis starten. +When the notebook opens in your browser, the notebook dashboard is displayed +with a list of the notebooks, files and subdirectories in the directory in which +the notebook server was started. In most cases you want to start a notebook +server in your project directory. .. image:: initial-jupyter-dashboard.png diff --git a/docs/genindex.rst b/docs/genindex.rst index 4c5dc9e3..19d610cf 100644 --- a/docs/genindex.rst +++ b/docs/genindex.rst @@ -1,4 +1,4 @@ .. Workarround for displaying the index in the toc -Stichwortverzeichnis -==================== +Index +===== diff --git a/docs/index.rst b/docs/index.rst index aebd7dda..bffc31a1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,13 @@ ================ -Jupyter-Tutorial +Jupyter Tutorial ================ -`Jupyter-Notebooks `_ erfreuen sich -bei Datenwissenschaftlern wachsender Beliebtheit und wurden zum -De-facto-Standard für schnelles Prototyping und explorative Analysen. Sie -beflügeln nicht nur Experimente und Innovationen enorm, sie machen auch den -gesamten Forschungsprozess schneller und zuverlässiger. Zudem entstehen viele -zusätzliche Komponenten, die die ursprünglichen Grenzen ihrer Nutzung erweitern -und neue Verwendungsmöglichkeiten ermöglichen. +`Jupyter notebooks `_ are growing in +popularity with data scientists and have become the de facto standard for +rapid prototyping and exploratory analysis. They inspire experiments and +innovations enormously and as well they make the entire research process faster +and more reliable. In addition, many additional components are created that +expand the original limits of their use and enable new uses. .. toctree:: :hidden: diff --git a/docs/intro.rst b/docs/intro.rst index 9e00db3d..8ca21e5d 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,5 +1,5 @@ -Einführung -========== +Introduction +============ Status ------ @@ -15,110 +15,108 @@ Status .. |Docs| image:: https://readthedocs.org/projects/jupyter-tutorial/badge/?version=latest :target: https://jupyter-tutorial.readthedocs.io/de/latest/ -Zielgruppe ----------- - -Die Nutzer von Jupyter-Notebooks sind vielfältig von Daten-Wissenschaftlern über --Ingenieure und -Analysten bis hin zu System-Ingenieuren. Dabei sind ihre -Fähigkeiten und Arbeitsabläufe sehr unterschiedlich. Eine der großen Stärken von -Jupyter-Notebooks ist jedoch, dass sie eine enge Zusammenarbeit dieser -unterschiedlichen Experten in funktionsübergreifenden Teams ermöglichen. - -* **Daten-Wissenschaftler** führen Experimente mit verschiedenen Koeffizienten - durch und fassen die Ergebnisse zusammen. -* **Daten-Ingenieure** überprüfen die Qualität des Codes und machen ihn robuster, - effizienter und skalierbar. -* **Daten-Analysten** führen systematische Untersuchungen der Daten durch, wobei - sie den von Dateningenieuren bereitgestellten Code verwenden. -* **System-Ingenieure** erstellen das `Hub `_, die - Kernel, Erweiterungen etc. und gewährleisten den möglichst reibungslosen - Betrieb dieser Infrastruktur. - -In diesem Tutorial wenden wir uns zunächst vor allem an System-Ingenieure, -die eine Plattform auf Basis von Jupyter-Notebooks aufbauen und betreiben -wollen. In der Folge erläutern wir dann, wie diese Plattform effektiv von -Datenwissenschaftlern, -Ingenieuren und -Analysten genutzt werden kann. - -Aufbau des Jupyter-Tutorial ---------------------------- - -Das Jupyter-Tutorial folgt ab Kapitel 3 dem prototypischen Verlauf eines -Forschungsprojekts: - -3. **Arbeitsbereich einrichten** mit der Installation und Konfiguration von - :doc:`workspace/ipython/index`, :doc:`workspace/jupyter/index` mit - :doc:`workspace/jupyter/nbextensions/index` und +Target group +------------ + +The users of Jupyter notebooks are diverse, from data scientists to data +engineers and analysts to system engineers. Their skills and workflows are very +different. However, one of the great strengths of Jupyter notebooks is that they +allow these different experts to work closely together in cross-functional +teams. + +* **Data scientists** + conduct experiments with different coefficients and summarise the results. + +* **Data engineers** + check the quality of the code and make it more robust, efficient and scalable. + +* **Data analysts** + perform systematic studies of the data using code provided by data engineers. + +* **System engineers** + create the hub, the kernel, extensions, etc. and ensure that this + infrastructure runs as smoothly as possible. + +In this tutorial, we primarily address system engineers who want to build and +operate a platform based on Jupyter notebooks. Then, we explain how this +platform can be used effectively by data scientists, data engineers, and +analysts. + +Structure of the Jupyter tutorial +--------------------------------- + +From Chapter 3, the Jupyter tutorial follows the prototype of a research +project: + +3. **Set up the workspace** with the installation and configuration of + :doc:`workspace/ipython/index`, + :doc:`workspace/jupyter/index` with + :doc:`workspace/jupyter/nbextensions/index` and :doc:`workspace/jupyter/ipywidgets/index`. -4. **Daten sammeln**, entweder durch eine :doc:`Rest-API ` oder - direkt von einer :doc:`HTML-Seite `. -5. **Daten bereinigen** ist eine wiederkehrende Aufgabe, die u.a. redundante, - inkonsistente oder falsch formatierte Daten entfernen oder modifizieren soll. -6. **Erschließen der Daten –** :doc:`viz/index` umfasst expolorative Analysen und - das Visualisieren von Daten. -7. **Refactoring** umfasst das Parametrisieren, Validieren und - Performance-Optimierungen, u.a. durch :doc:`Parallelisierung +4. **Collect data,** either through a :doc:`REST API ` or directly + from an HTML page. +5. **Cleaning up data** is a recurring task that includes Remove or modify + redundant, inconsistent, or incorrectly formatted data. +6. **Analyse data** through exploratory analysis and :doc:`visualising data + `. -8. **Produkt erstellen** umfasst das :doc:`productive/testing/index`, - :doc:`productive/logging` und :doc:`productive/documenting/index` der - Methoden und Funktionen sowie das :doc:`Erstellen von Paketen - `. -9. **Web-Anwendungen** können entweder aus Jupyter-Notebooks - :doc:`web/dashboards/index` generieren oder umfassendere - Applikationslogik benötigen, wie z.B. in - :doc:`pyviz:bokeh/embedding-export/flask` demonstriert, oder Daten über eine - `RESTful API - `_ - bereitstellen. - -Warum Jupyter? --------------- - -Wie können nun diese vielfältigen Aufgaben vereinfacht werden? Es wird sich -kaum ein Werkzeug finden, das all diese Aufgaben abdeckt und selbst für einzelne -Aufgaben sind häufig mehrere Werkzeuge notwendig. Daher suchen wir auf einer -abstrakteren Ebene allgemeinere Muster für Tools und Sprachen, mit denen Daten -analysiert und visualisiert sowie ein Projekt dokumentiert und präsentiert -werden kann. Genau dies wir mit dem `Project Jupyter `_ -angestrebt. - -Das Projekt Jupyter startete 2014 mit dem Ziel, ein konsistentes Set von -Open-Source-Tools für wissenschaftliche Forschung, reproduzierbare Workflows, -`Computational Narratives +8. **Creating a product** + includes :doc:`productive/testing/index`, :doc:`productive/logging` and + :doc:`productive/documenting/index` the methods and functions as well + as :doc:`creating packages `. +9. **Web applications** + can either generate dashboards from Jupyter notebooks or require more + comprehensive application logic, such as demonstrated in + :doc:`pyviz:bokeh/embedding-export/flask`, or provide data via a `RESTful API + `_. + +Why Jupyter? +------------ + +How can these diverse tasks be simplified? You will hardly find a tool that +covers all of these tasks, and several tools are often required even for +individual tasks. Therefore, on a more abstract level, we are looking for more +general patterns for tools and languages with which data can be analysed and +visualised and a project can be documented and presented. This is exactly what +we are aiming for with `Project Jupyter `_. + +The Jupyter project started in 2014 with the aim of creating a consistent set of +open source tools for scientific research, reproducible workflows, +`computational narratives `_ -und Datenanalyse zu erstellen. Bereits 2017 wurde Jupyter dann mit dem `ACM -Software Systems Award +and data analysis. In 2017, Jupyter received the `ACM Software Systems Award `_ -ausgezeichnet - eine prestigeträchtige Auszeichnung, die es u.a. mit Unix und -dem Web teilt. +– a prestigious award which, among other things, shares with Unix and the web. -Um zu verstehen, warum Jupyter-Notebooks so erfolgreich sind, schauen wir uns -die Kernfunktionen einmal genauer an: +To understand why Jupyter notebooks are so successful, let’s take a closer look +at the core functions: `Jupyter Notebook Format `_ - Jupyter Notebooks sind ein offenes, auf JSON basierendes Dokumentenformat - mit vollständigen Aufzeichnungen der Sitzungen des Benutzers und des - enthalten Code. + Jupyter Notebooks are an open, JSON-based document format with full records + of the user’s sessions and the code they contain. Interactive Computing Protocol - Das Notebook kommuniziert mit Rechenkernel über das *Interactive Computing - Protocol*, einem offenen Netzwerkprotokoll basierend auf JSON-Daten über - `ZMQ `_ und `WebSockets + The notebook communicates with the computing kernel via the *Interactive + Computing Protocol*, an open network protocol based on JSON data via `ZMQ + `_ and `WebSockets `_. :doc:`workspace/jupyter/kernels/index` - Kernel sind Prozesse, die interaktiven Code in einer bestimmten - Programmiersprache ausführen und die Ausgabe an den Benutzer zurückgeben. + Kernels are processes that execute interactive code in a specific + programming language and return the output to the user. -Jupyter-Infrastruktur ---------------------- +Jupyter infrastructure +---------------------- -Eine Plattform für die oben genannten Use Cases erfordert eine umfangreiche -Infrastruktur, die nicht nur die Bereitstellung der Kernel sowie die -Parametrisierung, Zeitsteuerung und Parallelisierung von Notebooks erlaubt, -sondern darüberhinaus auch die gleichmäßige Bereitstellung der Ressourcen. +A platform for the above-mentioned use cases requires an extensive +infrastructure that not only allows the provision of the kernel and the +parameterization, time control and parallelisation of notebooks, but also the +uniform provision of resources. -Mit diesem Tutorial wird eine Plattform bereitgestellt, die über Jupyter -Notebooks hinaus schnelle, flexible und umfassende Datenanalysen ermöglicht. -Aktuell gehen wir jedoch noch nicht darauf ein, wie sie sich um *Streaming -Pipelines* und *Domain Driven Data Stores* erweitern lässt. +This tutorial provides a platform that enables fast, flexible and comprehensive +data analysis beyond Jupyter notebooks. At the moment, however, we are not yet +going into how it can be expanded to include streaming pipelines and +domain-driven data stores. -Die Beispiele des Jupyter-Tutorials könnt Ihr jedoch auch lokal erstellen und -ausführen. +However, you can also create and run the examples in the Jupyter tutorial +locally. diff --git a/docs/productive/documenting/docstrings.rst b/docs/productive/documenting/docstrings.rst index 91b8d0aa..a599f367 100644 --- a/docs/productive/documenting/docstrings.rst +++ b/docs/productive/documenting/docstrings.rst @@ -1,23 +1,23 @@ Docstrings ========== -Mit der Sphinx-Erweiterung `sphinx.ext.autodoc -`_ lassen -sich auch Docstrings in die Dokumentation übernehmen. Dabei lassen sich die -folgenden drei Direktiven angeben: +With the Sphinx extension `sphinx.ext.autodoc +`_, +docstrings can also be included in the documentation. The following three +directives can be specified: .. rst:directive:: automodule autoclass autoexception -Diese dokumentieren ein Modul, eine Klasse oder eine Exception anhand des -Docstrings des jeweiligen Objekts. +These document a module, a class or an exception using the docstring of the +respective object. Installation ------------ -Üblicherweise ist ``sphinx.ext.autodoc`` bereits in der -Sphinx-Konfigurationsdatei ``docs/conf.py`` angegeben: +``sphinx.ext.autodoc`` is usually already specified in the Sphinx configuration +file ``docs/conf.py``: .. code-block:: python @@ -26,34 +26,34 @@ Sphinx-Konfigurationsdatei ``docs/conf.py`` angegeben: … ] -Wenn euer Paket und die zugehörige Dokumentation Teil des gleichen Repository -sind, haben sie immer die gleiche relative Position im Dateisystem. In diesem -Fall könnt ihr die Sphinx-Konfiguration einfach so bearbeiten, dass ``sys.path`` -den relativen Pfad zum Paket angibt, also: +If your package and its documentation are part of the same repository, they will +always have the same relative position in the filesystem. In this case you can +simply edit the Sphinx configuration for ``sys.path`` to indicate the relative +path to the package, so: .. code-block:: python sys.path.insert(0, os.path.abspath('..')) import requests -Wen ihr eure Sphinx-Dokumentation in einer virtuellen Umgebung installiert -habt, könnt ihr dort auch euer Paket installieren mit: +If you have installed your Sphinx documentation in a virtual environment, you +can also install your package there with: -.. code-block:: python +.. code-block:: console $ pipenv install my.package -bzw., wenn ihr auch das Paket weiterentwickeln wollt mit: +or, if you want to develop the package further with: .. code-block:: console $ pipenv install -e https://github.com/veit/my.package.git -Beispiele ---------- +Examples +-------- -Hier einige Beispiele aus der API-Dokumentation des `requests -`_-Modul: +Here are some examples from the API documentation for the `requests +`_ module: .. code-block:: rest @@ -78,7 +78,8 @@ Hier einige Beispiele aus der API-Dokumentation des `requests .. autoclass:: Session :inherited-members: -Dies führt zu :doc:`docstrings-example`, generiert aus den folgenden Docstrings: +This leads to the :doc:`docstrings-example`, generated from the following +docstrings: * `requests.head `_ * `requests.RequestException `_ @@ -88,8 +89,7 @@ Dies führt zu :doc:`docstrings-example`, generiert aus den folgenden Docstrings :inherited-members: .. note:: - Ihr solltet euch beim Schreiben von Docstrings an die folgenden - Anleitungen halten: + You should follow these guidelines when writing docstrings: * `Python Style Guide: comments `_ @@ -99,13 +99,14 @@ Dies führt zu :doc:`docstrings-example`, generiert aus den folgenden Docstrings ``sphinx-autodoc-typehints`` ---------------------------- -Mit `PEP 484 `_ wurde eine -Standardmethode zum Ausdrücken von Typen in Python-Code eingeführt. Damit lassen -sich auch Typen in Docstrings anders ausdrücken. Dabei bietet die Variante mit -Typen gemäß PEP 484 den Vorteil, dass Typenprüfer und IDEs zur statischen -Codeanalyse genutzt werden können. +With `PEP 484 `_ a standard method +for expressing types in Python code was introduced. This also allows types to be +expressed differently in docstrings. The variant with types according to PEP 484 +has the advantage that type testers and IDEs can be used for static code +analysis. Python 3 type annotations: + .. code-block:: python def func(arg1: int, arg2: str) -> bool: @@ -124,6 +125,7 @@ Python 3 type annotations: return True Types in Docstrings: + .. code-block:: python def func(arg1, arg2): @@ -142,17 +144,17 @@ Types in Docstrings: return True .. note:: - `Python2/3-kompatible Anmerkungen + `Python 2/3 compatible annotations `_ - werden aktuell nicht von Sphinx unterstützt und erscheinen nicht in der - generierten Dokumentation. + are currently not supported by Sphinx and do not appear in the generated + documentation. ``sphinx.ext.napoleon`` ----------------------- -Die Sphinx-Erweiterung `sphinx.ext.napoleon -`_ erlaubt euch, verschiedene -Abschnitte in Docstrings zu definieren, u.a.: +The sphinx extension `sphinx.ext.napoleon +`_ allows you to define +different sections in docstrings, including: * ``Attributes`` * ``Example`` @@ -162,15 +164,16 @@ Abschnitte in Docstrings zu definieren, u.a.: * ``Warning`` * ``Yield`` -Dabei unterscheidet ``sphinx.ext.napoleon`` zwei Stilen von Docstrings: +There are two styles of docstrings in ``sphinx.ext.napoleon``: * `Google `_ * `NumPy `_ -Die wesentlichen Unterschiede sind, dass Google Einrückungen verwendet und NumPy -Unterstriche: +The main differences are that Google uses indentations and NumPy uses +underscores: Google: + .. code-block:: python def func(arg1, arg2): @@ -189,6 +192,7 @@ Google: return True NumPy: + .. code-block:: python def func(arg1, arg2): @@ -211,5 +215,5 @@ NumPy: """ return True -Die detailierten Konfigurationsoptionen findet ihr in `sphinxcontrib.napoleon.Config +You can find the detailed configuration options in `sphinxcontrib.napoleon.Config `_. diff --git a/docs/productive/documenting/extensions.rst b/docs/productive/documenting/extensions.rst index 256b5519..3efd0d66 100644 --- a/docs/productive/documenting/extensions.rst +++ b/docs/productive/documenting/extensions.rst @@ -1,74 +1,70 @@ Extensions ========== -Built-in Extensions +Built-in extensions ------------------- `sphinx.ext.autodoc `_ - Dokumentation aus Docstrings integrieren + Integrate documentation from docstrings `sphinx.ext.autosummary `_ - generiert Zusammenfassungen von Funktionen, Methoden und Attributen - aus Docstrings + generates summaries of functions, methods and attributes from docstrings `sphinx.ext.autosectionlabel `_ - referenziert Abchnitt unter Verwendung des Titels + references section using the title `sphinx.ext.graphviz `_ - Rendering von `Graphviz `_-Graphen + Rendering of `Graphviz `_ graphs `sphinx.ext.ifconfig `_ - schließt Inhalte nur unter bestimmten Bedingungen ein + includes content only under certain conditions `sphinx.ext.intersphinx `_ - erlaubt die Verlinkung von anderen Projekt-Dokumentationen + allows the linking of other project documentation `sphinx.ext.mathjax `_ Rendering via JavaScript `sphinx.ext.napoleon `_ - Support für NumPy- und Google-Style Docstrings + Support for NumPy and Google style docstrings `sphinx.ext.todo `_ - Unterstützung für ToDo-Items + Support for ToDo items `sphinx.ext.viewcode `_ - fügt Links zum Quellcode der Sphinx-Dokumentation hinzu + adds links to the source code of the Sphinx documentation .. seealso:: - Einen vollständigen Überblick erhaltet ihr unter `Sphinx Extensions + You can get a complete overview at `Sphinx Extensions `_ -Third-party Extensions +Third-party extensions ---------------------- `nbsphinx `_ Jupyter Notebooks in Sphinx `jupyter-sphinx `_ - erlaubt das Rendering von Jupyter interactive widgets in Sphinx, - s.a. + allows rendering of Jupyter interactive widgets in Sphinx, see also `Embedding Widgets in the Sphinx HTML Documentation `_ `numpydoc `_ - `NumPy `_’s Sphinx-Extension + `NumPy `_’s Sphinx extension `Releases `_ - schreibt eine Changelog-Datei + writes a changelog file `sphinxcontrib-napoleon `_ - Napoleon ist ein Pre-Processor zum Parsen von NumPy- und Google-Style - Docstrings + Napoleon is a pre-processor for parsing NumPy- and Google-style docstrings `Sphinx-autodoc-typehints `_ - Type hints-Support für die Sphinx autodoc-Extension + Type hints support for the Sphinx autodoc extension `sphinx-git `_ `git `_-Changelog for Sphinx `sphinx-intl `_ - Sphinx-Erweiterung für Übersetzungen + Sphinx extension for translations `sphinx-autobuild `_ - überwacht ein Sphinx-Repository und erstellt eine neue Dokumentation - sobald Änderungen gemacht wurden + monitors a Sphinx repository and creates new documentation as soon as + changes are made `Sphinxcontrib-mermaid `_ - erlaubt, Mermaid- Grafiken in Ihre Dokumente einbetten. + allows you to embed Mermaid graphics in your documents. -Eigene Extensions ------------------ +Own Extensions +-------------- -Lokale Erweiterungen in einem Projekt sollten relativ zur Dokumentation -angegeben werden. Hierfür wird in der Sphinx-Konfigurationsdatei -``docs/conf.py`` der entsprechende Pfad angegeben. Wenn eure Erweiterung -im Verzeichnis ``exts`` in der Datei ``foo.py`` liegt, dann wird in der -``conf.py`` folgendes eingetragen: +Local extensions in a project should be specified relative to the documentation. +The appropriate path is specified in the Sphinx configuration ``docs/conf.py``. +If your extension is in the directory ``exts`` in the file ``foo.py``, then the +``conf.py`` should look like this: .. code-block:: python diff --git a/docs/productive/documenting/index.rst b/docs/productive/documenting/index.rst index ea245c8f..8c632095 100644 --- a/docs/productive/documenting/index.rst +++ b/docs/productive/documenting/index.rst @@ -1,31 +1,29 @@ -Dokumentieren -============= +Document +======== -Damit Euer Produkt sinnvoll genutzt werden kann, sind Dokumentationen sowohl für -die Zielgruppen Daten-Wissenschaftler und Daten-Ingenieure als auch für -System-Ingenieure erforderlich: +So that your product can be used effectively, documentation is required for the +target groups of data scientists and data engineers as well as for system +engineers: -* Daten-Wissenschaftler wollen dokumentiert sehen +* Data scientists want to see documented - * welche Probleme Euer Produkt löst und was die Hauptfunktionen und - Limitationen der Software sind (``README``) - * wie das Produkt beispielhaft verwendet werden kann - * welche Veränderungen in aktuelleren Software-Versionen gekommen sind - (``CHANGELOG``) + * which problems your product solves and what the main functions and + limitations of the software are (``README``) + * how the product can be used + * which changes have come in more recent software versions (``CHANGELOG``) -* Daten-Ingenieure wollen wissen, wie sie mit Fehlerbehebungen zur Verbesserung - des Produkts beitragen können (``CONTRIBUTING``) und wie sie mit anderen - kommunizieren (``CODE_OF_CONDUCT``) können -* System-Ingenieure benötigen eine Installationsanleitung für Euer Produkt - und der erforderlichen Abhängigkeiten +* Data engineers want to know how troubleshooting can help improve the product + (``CONTRIBUTING``) and how they can communicate with others + (``CODE_OF_CONDUCT``) +* System engineers need installation instructions for your product and the + required dependencies -Alle gemeinsam benötigen Informationen, wie das Produkt lizenziert ist -(``LICENSE``-Datei oder ``LICENSES``-Ordner) und wie sie bei Bedarf Hilfe -erhalten können. +Together, they all need information about how the product is licensed +(``LICENSE`` file or ``LICENSES`` folder and how they can get help if needed. -Um schnell einen Überblick übr ein Produkt zu erhalten, sind sog. Badges -hilfreich. Für das `cookiecutter-namespace-template -`_ sind dies z.B.: +Badges are helpful in getting a quick overview of a product. For the +`cookiecutter-namespace-template +`_ these are, for example: |Downloads| |Updates| |Versions| |Contributors| |License| |Docs| @@ -42,43 +40,37 @@ hilfreich. Für das `cookiecutter-namespace-template .. |Docs| image:: https://readthedocs.org/projects/cookiecutter-namespace-template/badge/?version=latest :target: https://cookiecutter-namespace-template.readthedocs.io/en/latest/ -Für umfangreiche Dokuemtationen könnt Ihr z.B. `Sphinx -`_ verwenden, ein Dokumentationswerkzeug, das -:doc:`rest`, eine einfache Auszeichnungssprache, in HTML oder auch PDF, -EPub und Manpages umwandelt. Auch das Jupyter-Tutorial ist mit Sphinx erstellt -worden. Um einen ersten Eindruck von Sphinx zu erhalten, könnt Ihr Euch den -Quellcode dieser Seite anschauen indem Ihr am Fuss dieser Seite dem Link +For extensive documentation you can, for example, use `Sphinx +`_, a documentation tool that converts :doc:`rest`, +a simple markup language, into HTML or PDF, EPub and man pages. The Jupyter +tutorial was also created with Sphinx. To get a first impression of the Sphinx, +you can have a look at the source code of this page by following the link `Sources <../../_sources/productive/sphinx/index.rst.txt>`_ folgt. -Ursprünglich wurde Sphinx für die Dokumentation von Python entwickelt und wird -heute auch in fast allen Python-Projekten verwendet, u.a. für `NumPy und SciPy +Originally, Sphinx was developed for the documentation of Python and is now used +in almost all Python projects, including `NumPy und SciPy `_, `Matplotlib `_, `Pandas -`_ und `SQLAlchemy +`_ and `SQLAlchemy `_. -Zur Verbreitung von Sphinx unter den Python-Entwicklern dürfte auch das Sphinx -`autodoc -`_-Feature -beigetragen haben, mit dem Dokumentationen aus Python :doc:`docstrings` -erzeugt werden können. Insgesamt erlaubt Sphinx Entwicklern, *in place* eine -vollständige Dokumentation erstellen zu können. Häufig wird die Dokumentation -auch im selben :doc:`Git <../git/index>`-Repository gespeichert, sodass das -Erstellen der jeweils aktuellen Software-Dokumentation einfach bleibt. - -Sphinx wird auch in Projekten außerhalb der Python-Community verwendet, z.B. für -die Dokumentation des Linux Kernels: `Kernel documentation update +The Sphinx `autodoc +`_ feature, +which can be used to create documentation from Python :doc:`docstrings`, may +also be conducive to the spread of Sphinx among Python developers. Overall, +Sphinx allows developers to create complete documentation in place. Often the +documentation is also stored in the same :doc:`Git <../git/index>` repository, +so that the creation of the latest software documentation remains easy. + +Sphinx is also used in projects outside the Python community, e.g. for the +documentation of the Linux kernel: `Kernel documentation update `_. -Um die Erstellung von Dokumentationen weiter zu vereinfachen, wurde -`Read the Docs `_ entwickelt. Read the Docs -vereinfacht das Erstellen und Veröffentlichen von Dokumentation nach jedem -*Commit*. +`Read the Docs `_ was developed to forther simplify +documentation. Read the Docs makes it easy to create and publish documentation +after each commit. .. seealso:: - * `Christina Czeschik und Matthias Lindhorst: Weniger schlecht über IT - schreiben - `_ * `Google developer documentation style guide `_ * `Google Technical Writing Courses for Engineers diff --git a/docs/productive/documenting/intersphinx.rst b/docs/productive/documenting/intersphinx.rst index 08207d8c..a16d6450 100644 --- a/docs/productive/documenting/intersphinx.rst +++ b/docs/productive/documenting/intersphinx.rst @@ -3,12 +3,12 @@ Intersphinx `sphinx.ext.intersphinx `_ -erlaubt die Verlinkung von anderen Projekt-Dokumentationen. +allows the linking of other project documentation. -Konfiguration +Configuration ------------- -In ``source/conf.py`` muss Intersphinx als Erweiterung angegeben werden: +In ``source/conf.py`` Intersphinx must be indicated as an extension: .. code-block:: python @@ -17,7 +17,7 @@ In ``source/conf.py`` muss Intersphinx als Erweiterung angegeben werden: 'sphinx.ext.intersphinx', ] -Anschließend können externe Sphinx-Dokumentationen angegeben werden, z.B. mit: +External Sphinx documentation can then be specified, e.g. with: .. code-block:: python @@ -26,7 +26,7 @@ Anschließend können externe Sphinx-Dokumentationen angegeben werden, z.B. mit: 'bokeh': ('https://bokeh.pydata.org/en/latest/', None) } -Für ein Inventar können jedoch auch alternative Dateien angegeben werden, z.B.: +However, alternative files can also be specified for an inventory, for example: .. code-block:: python @@ -35,11 +35,11 @@ Für ein Inventar können jedoch auch alternative Dateien angegeben werden, z.B. ... } -Linkziele ermitteln -------------------- +Determine link targets +---------------------- -Um die in einem Inventar zur Verfügung stehenden Links zu ermitteln, könnt Ihr -z.B. folgendes eingeben: +To determine the links available in an inventory, you can enter the following, +for example: .. code-block:: console @@ -50,11 +50,11 @@ z.B. folgendes eingeben: PyArg_Parse c-api/arg.html#c.PyArg_Parse … -Link erstellen --------------- +Create a link +------------- -Um nun z.B. auf https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse zu -verlinken, kann eine der folgenden Varianten angegeben werden: +In order to link to https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse, one +of the following variants can be specified: :c:func:`PyArg_Parse` .. code-block:: rest @@ -71,22 +71,22 @@ verlinken, kann eine der folgenden Varianten angegeben werden: :c:func:`Parsing arguments ` -Benutzerdefinierte Links ------------------------- +Custom links +------------ -Ihr könnt auch eigene ``intersphinx``-Zuordnungen erstellen, z.B. wenn -``objects.inv`` Fehler hat wie bei `Beautyfull Soup -`_. +You can also create your own ``intersphinx`` assignments, e.g. if +``objects.inv`` in `Beautyfull Soup +`_ has errors. -Der Fehler kann behoben werden mit: +The error can be corrected with: -#. Installation von ``sphobjinv``: +#. Installation of ``sphobjinv``: .. code-block:: console $ pipenv install sphobjinv -#. Anschließend kann die Originaldatei heruntergeladen werden mit: +#. Then the original file can be downloaded with: .. code-block:: console @@ -96,7 +96,7 @@ Der Fehler kann behoben werden mit: $ curl -O https://www.crummy.com/software/BeautifulSoup/bs4/doc/objects.inv $ mv objects.inv bs4_objects.inv -#. Ändern der Sphinx-Konfiguration in ``docs/source/conf.py``: +#. Change the Sphinx configuration ``docs/source/conf.py``: .. code-block:: console @@ -105,15 +105,15 @@ Der Fehler kann behoben werden mit: 'bs4': ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', "_intersphinx/bs4_objects.inv") } -#. Konvertieren in eine Textdatei: +#. Convert to a text file: .. code-block:: console $ pipenv run sphobjinv convert plain bs4_objects.inv bs4_objects.txt -#. Editieren der Textdatei +#. Editing the text file - z.B.: + e.g.: .. code-block:: console @@ -121,8 +121,7 @@ Der Fehler kann behoben werden mit: bs4.BeautifulSoup.get_text py:method 1 index.html#get-text - bs4.element.Tag py:class 1 index.html#tag - - Diese Einträge lassen sich dann in einer Sphinx-Dokumentation referenzieren - mit: + These entries can then be referenced in a Sphinx documentation with: .. code-block:: rest @@ -131,33 +130,32 @@ Der Fehler kann behoben werden mit: - :class:`bs4.element.Tag` .. note:: - Beachtet dabei die `Sphinx objects.inv v2 Syntax - `_ dieser - Textdateien. + Please note the `Sphinx objects.inv v2 Syntax + `_ of these text + files. -#. Neue ``objects.inv``-Datei erstellen: +#. Create a new ``objects.inv`` file: .. code-block:: console $ pipenv run sphobjinv convert zlib bs4_objects.txt bs4_objects.txt -#. Sphinx-Dokumentation erstellen: +#. Create Sphinx documentation: .. code-block:: console $ pipenv run sphinx-build -ab html source/ build/ -Rollen hinzufügen ------------------ +Add roles +--------- -Wenn ihr eine Fehlermeldung erhaltet, dass eine bestimmte Textrolle unbekannt -sei, z.B. +If you get an error message that a certain text role is unknown, e.g. .. code-block:: console WARNING: Unknown interpreted text role "confval". -so könnt ihr diese in der ``conf.py`` hinzufügen: +so you can add them in the ``conf.py``: .. code-block:: python diff --git a/docs/productive/documenting/rest.rst b/docs/productive/documenting/rest.rst index 9dccbe29..366d3934 100644 --- a/docs/productive/documenting/rest.rst +++ b/docs/productive/documenting/rest.rst @@ -1,58 +1,56 @@ reStructuredText ================ -Kurzanleitung -------------- +Quick guide +----------- Den folgenden reStructuredText könnt ihr euch als HTML anschauen unter :doc:`rest-example`:: - Titel mit Satzzeichen unterstreichen - ===================================== + Underline the title with punctuation marks + ========================================== - Wechselt für Untertitel das Satzzeichen - --------------------------------------- + Change the punctuation mark for subtitles + ----------------------------------------- - *Italic*, **fett** und ``vorformatiert`` - `Hyperlink `_ `Link`_ + *Italic*, **bold** und ``preformatted`` + `hyperlink `_ `link`_ - .. _Link: http://en.wikipedia.org/wiki/Link_(The_Legend_of_Zelda) + .. _link: http://en.wikipedia.org/wiki/Link_(The_Legend_of_Zelda) .. image:: python-logo.png - .. Ein Kommentarblock beginnt mit zwei Punkten und kann weiter eingerückt - werden. + .. A comment block begins with two points and can be indented further - Ein Absatz besteht aus einer oder mehreren Zeilen mit nicht eingerücktem - Text, getrennt aus dem Material oben und unten durch Leerzeilen. + A paragraph consists of one or more lines of non-indented text, separated + from the material above and below by blank lines. - »Block-Anführungszeichen sehen aus wie Absätze, sind aber eingerückt mit - einem oder mehreren Leerzeichen.« + »Block quotation marks look like paragraphs, but are indented with one + or more spaces.« - | Aufgrund des Pipe-Zeichens wird dies zu einer Zeile. - | Und dies wird eine andere Zeile werden. + | Because of the pipe character, this becomes one line. + | And this will be another line. - Begriff - Definition für den Begriff - Anderer Begriff - …und seine Definition + term + Definition of the term + Different term + …and its definition - * Jeder Eintrag in einer Liste beginnt mit einem Sternchen (oder ``1.``, - ``a.`` usw.). - * Listenelemente können für mehrere Zeilen angezeigt werden, solange die - Listenelemente eingerückt bleiben + * Each entry in a list begins with an asterisk (or ``1.``, + ``a.`` etc.). + * List items can be displayed for multiple lines as long as the list items + remain indented - Codeblöcke werden mit einem Doppelpunkt eingeführt und eingerückt:: + Blocks of code are introduced and indented with a colon:: import docutils print help(docutils) - >>> print 'Aber doctests beginnen mit ">>>" und brauchen keine Einrückung.' + >>> print 'But doctests start with ">>>" and don’t need to be indented.' .. note:: - Wenn der Inhalt von ``long_description`` in - ``setuptools.setup()`` in reStructured Text geschrieben ist, wird es im - :term:`Python Package Index (PyPI)` als wohlformattiertes HTML - ausgegeben. + If the content of ``long_description`` in ``setuptools.setup()`` is written + in reStructured Text, it is displayed as well-formatted HTML on the + :term:`Python Package Index (PyPI)`. .. seealso:: * `reStructuredText Primer @@ -60,14 +58,14 @@ Den folgenden reStructuredText könnt ihr euch als HTML anschauen unter * `reStructuredText Quick Reference `_ -Direktiven +Directives ---------- -reStructuredText lässt sich durch sog. `Directives -`_ erweitern. -Hiervon macht Sphinx umfassend Gebrauch. Hier einige Beispiele: +reStructuredText can be expanded with `Directives +`_. +Sphinx makes extensive use of this. Here are some examples: -Inhaltsverzeichnis +Table of Contents .. code-block:: rest @@ -83,7 +81,7 @@ Inhaltsverzeichnis rest docstrings -Meta-Informationen +Meta information .. code-block:: rest @@ -93,7 +91,7 @@ Meta-Informationen .. sectionauthor:: Veit Schiele .. codeauthor:: Veit Schiele -Code-Block +Code block .. code-block:: rest @@ -115,7 +113,7 @@ Code-Block print 'This one is not...' print '...but this one is.' -Siehe auch +See also .. code-block:: rest @@ -127,7 +125,7 @@ Siehe auch `Sphinx Directives `_ -Glossar +Glossary .. code-block:: rest diff --git a/docs/productive/documenting/start.rst b/docs/productive/documenting/start.rst index 4349d16f..60b3b999 100644 --- a/docs/productive/documenting/start.rst +++ b/docs/productive/documenting/start.rst @@ -1,7 +1,7 @@ -Sphinx-Projekt erstellen -======================== +Create a Sphinx project +======================= -Installation und Start +Installation and start ---------------------- .. code-block:: console @@ -40,7 +40,7 @@ Installation und Start Creating file docs/Makefile. Creating file docs/make.bat. -Sphinx-Layout +Sphinx layout ------------- :: @@ -56,6 +56,6 @@ Sphinx-Layout ├── index.rst └── make.bat -``index.rst`` ist die initiale Datei für die Dokumentation, in der sich das -Inhaltsverzeichnis befindet. Das Inhaltsverzeichnis wird von euch erweitert -werden sobald ihr neue ``*.rst``-Dateien hinzufügt. +``index.rst`` is the initial file for the documentation, in which the table of +contents is located. The table of contents will be expanded by you as soon as you +add new ``*.rst`` files. diff --git a/docs/productive/dvc/dag.rst b/docs/productive/dvc/dag.rst index 607c0363..a9cf2149 100644 --- a/docs/productive/dvc/dag.rst +++ b/docs/productive/dvc/dag.rst @@ -1,8 +1,8 @@ -Pipelines anzeigen -================== +View pipelines +============== -Solche Datenpipelines lassen sich anzeigen oder als Abhängigkeitsgraph -darstellen mit ``dvc dag``: +Such data pipelines can be displayed or represented as a dependency graph with +``dvc dag``: .. code-block:: console @@ -42,8 +42,8 @@ darstellen mit ``dvc dag``: train.dvc evaluate.dvc -* Mit ``dvc dag --dot`` kann auch eine ``.dot``-Datei für `Graphviz - `_ generiert werden: +* With ``dvc dag --dot`` a ``.dot`` file for `Graphviz + `_ is generated: .. graphviz:: diff --git a/docs/productive/dvc/index.rst b/docs/productive/dvc/index.rst index d224d621..c465fe49 100644 --- a/docs/productive/dvc/index.rst +++ b/docs/productive/dvc/index.rst @@ -1,40 +1,36 @@ -Daten verwalten mit ``DVC`` -=========================== - -Für Datenanalysen und vor allem bei Machine Learning ist es äußerst wertvoll, -verschiedene Versionen von Analysen, die mit verschiedenen Datensätzen und -Parametern durchgeführt wurden, reproduzieren zu können. Um jedoch -reproduzierbare Analysen zu erhalten, müssen sowohl die Daten als auch das -Modell (einschließlich der Algorithmen, Parameter. etc.) versioniert werden. -Die Versionierung von Daten für reproduzierbare Analysen ist aufgrund der -Datengröße ein größeres Problem als die Versionierung von Modellen. Werkzeuge -wie `DVC `_ helfen bei der Verwaltung von Daten indem Nutzer -diese mit einem :doc:`Git <../git/index>`-artigen Workflow an einen entfernten -Datenspeicher übertragen können. Hierdurch vereinfacht sich der Abruf bestimmter -Versionen von Daten um eine Analyse zu reproduzieren. - -DVC wurde entwickelt um ML-Modelle und Datensätze igemeinsam nutzen zu können -und nachvollziehbar zu verwalten. Es arbeitet zwar mit verschiedenen -Versionsverwaltungen zusammen, benötigt diese jedoch nicht. Im Gegensatz z.B. zu -`DataLad `_/`git-annex -`_ ist es auch nicht auf Git als -Versionsverwaltung beschränkt sondern kann z.B auch zusammen mit Mercurial -verwendet werden, siehe `github.com/crobarcro/dvc/dvc/scm.py -`_. Zudem nutzt es -ein eigenes System zum Speichern der Dateien mit Unterstützung u.a. für SSH und -HDFS. - -DataLad konzentriert sich hingegen mehr auf die Entdeckung und Verwendung von -Datasets, die dann einfach mit Git verwaltet werden. DVC hingegen speichert -jeden Schritt der Pipeline in einer separaten ``.dvc``-Datei, die dann durch -Git verwaltet werden kann. - -Diese ``.dvc``-Dateien erlauben jedoch praktische Tools zur Manipilation und -Visualisierung von DAGs, siehe z.B. die :ref:`Visualisierung der DAGs +Manage data with ``DVC`` +======================== + +For data analysis, and especially machine learning, it is extremely valuable to +be able to reproduce different versions of analyses that have been carried out +with different data sets and parameters. However, in order to obtain +reproducible analyses, both the data and the model (including the algorithms, +parameters, etc.) must be versioned. Versioning data for reproducible analysis +is a bigger problem than versioning models because of the size of the data. +Tools like `DVC `_ help manage data by allowing users to +transfer it to a remote data store using a :doc:`Git <../git/index>` like +workflow. This simplifies the retrieval of certain versions of data in order to +reproduce an analysis. + +DVC was developed to be able to use ML models and data sets together and to +manage them in a comprehensible manner. It works with different version +managements, but does not need them. In contrast to `DataLad +`_/`git-annex `_, +for example, it is not limited to Git as version management, but can also be +used together with Mercurial, see `github.com/crobarcro/dvc/dvc/scm.py +`_. It also uses its +own system for storing files with support for SSH and HDFS, among others. + +DataLad, on the other hand, focuses more on discovering and consuming datasets, +which are then easily managed with Git. DVC, on the other hand, stores each step +in the pipeline in a separate ``.dvc`` file that can then be managed by Git. + +These ``.dvc`` files, however, allow practical tools for manipulating and +visualizing DAGs, see, for example, :ref:`visualisation of DAGs `. -Schließlich lassen sich mit :ref:`dvc remote ` auch -externe Abhängigkeiten angeben. +Finally, external dependencies can also be specified with :ref:`dvc remote +`. .. seealso:: * `Tutorial `_ @@ -44,17 +40,17 @@ externe Abhängigkeiten angeben. Installation ------------ -DVC lässt sich mit Pipenv installieren. Beachtet dabei jedoch bitte, dass ihr -hierbei die Extras explizit angeben müsst. Dies können ``[ssh]``, ``[s3]``, -``[gs]``, ``[azure]``, und ``[oss]`` oder ``[all]`` sein. Für ``ssh`` sieht das -Kommando dann so aus: +Finally, external dependencies can also be specified with Pipenv. Please note, +however, that you have to explicitly state the extras. This can be ``[ssh]``, +``[s3]``, ``[gs]``, ``[azure]``, and ``[oss]`` or ``[all]``. For ``ssh`` the +command looks like this: .. code-block:: console $ pipenv install dvc[ssh] -Alternativ kann DVC auch über das Paketmanagement von Ubuntu/Debian installiert -werden mit: +Alternatively, DVC can also be installed via the package management of +Ubuntu/Debian with: .. code-block:: console @@ -62,18 +58,18 @@ werden mit: $ sudo apt update $ sudo apt install dvc -Für macOS lässt sich DVC installieren mit: +For macOS DVC can be installed with: .. code-block:: console $ brew install iterative/homebrew-dvc/dvc .. note:: - Bitte beachtet, dass das folgende Beispiel mit einer aktuellen DVC-Version - erstellt wurde (1.0.0a9), die z.T. eine andere Syntax als frühere Versionen - verwendet. Dies könnt Ihr aktuell (8. Juni 2020) nur mit pip installieren:: + Please note that the following example was created with a current DVC + version (1.0.0a9), which partly uses a different syntax than earlier + versions. You can currently (8th June 2020) only install this with pip: - .. code-block:: console + .. code-block:: console $ pipenv install dvc[all]==1.0.0a9 diff --git a/docs/productive/dvc/init.rst b/docs/productive/dvc/init.rst index a68f0984..26d5acce 100644 --- a/docs/productive/dvc/init.rst +++ b/docs/productive/dvc/init.rst @@ -1,7 +1,7 @@ -Projekt erstellen -================= +Create a project +================ -DVC lässt sich einfach initialisieren mit: +DVC can be easily initialised with: .. code-block:: console @@ -10,24 +10,23 @@ DVC lässt sich einfach initialisieren mit: $ git init $ dvc init $ git add .dvc - $ git commit -m "Initialize DVC" + $ git commit -m "Initialise DVC" ``dvc init`` - erstellt ein Verzeichnis ``.dvc/`` mit ``config``, ``.gitignore`` und - ``cache``-Verzeichnis. + creates a directory ``.dvc/`` with ``config``, ``.gitignore`` and + ``cache`` directory. ``git commit`` - stellt ``.dvc/config`` und ``.dvc/.gitignore`` unter Git-Versionskontrolle. + puts ``.dvc/config`` and ``.dvc/.gitignore`` under version control. -Konfigurieren -------------- +Configure +--------- .. _dvc-remote: -Bevor DVC verwendet wird, sollte noch ein entfernter Speicherplatz (*remote -storage*) eingerichtet werden. Dieser sollte für alle zugänglich sein, die auf -die Daten oder das Modell zugreifen sollen. Es ähnelt der Verwendung eines -Git-Server. Häufig ist das jedoch auch ein NFS-Mount, der z.B. folgendermaßen -eingebunden werden kann: +Before DVC is used, even a remote storage is established. This should be +accessible to everyone who should access the data or the model. It’s similar to +using a Git server. Often, however, this is also an NFS mount, which can be +integrated as follows, for example: .. code-block:: console @@ -39,23 +38,22 @@ eingebunden werden kann: 1 file changed, 4 insertions(+) ``-d``, ``--default`` - Standardwert für den entfernten Speicherplatz + Default value for the space removed ``local`` - Name des entfernten Speicherplatz + Name of the remote location ``/var/dvc-storage`` - URL des entfernten Speicherplatzes + URL of the remote location - Daneben werden noch weitere Protokolle unterstützt, die dem Pfad - vorangestellt werden, u.a. ``ssh:``, ``hdfs:``, ``https:``. + In addition, other protocols are supported, which are preceded by the path, + including ``ssh:``, ``hdfs:`` and ``https:``. -Es kann also einfach noch ein weterer entfernter Datenspeicher hinzugefügt -werden, z.B. mit: +Another remote data storage can simply be added, e.g. with: .. code-block:: console $ dvc remote add webserver https://dvc.example.org/myproject -Die zugehörige Konfigurationsdatei ``.dvc/config`` sieht dann so aus: +The associated configuration file ``.dvc/config`` looks like this: .. code-block:: ini @@ -66,12 +64,11 @@ Die zugehörige Konfigurationsdatei ``.dvc/config`` sieht dann so aus: ['remote "webserver"'] url = https://dvc.example.org/myproject -Daten und Verzeichnisse hinzufügen ----------------------------------- +Add data and directories +------------------------ -Mit DVC könnt ihr Dateien, ML-Modelle, Verzeichnisse und Zwischenergebnisse mit -Git speichern und versionieren, ohne dass der Dateiinhalt in Git eingecheckt -werden muss: +With DVC you can save and version files, ML models, directories and intermediate +results with Git without having to check the file content into Git: .. code-block:: console @@ -79,53 +76,52 @@ werden muss: -o data/data.xml $ dvc add data/data.xml -Dies fügt die Datei ``data/data.xml`` in ``data/.gitignore`` hinzu und -schreibt die Metanangaben in ``data/data.xml.dvc``. Weitere Informationen -zum Dateiformat der ``*.dvc``-Datei erhaltet ihr unter `DVC-File Format +This will add the file ``data/data.xml`` in ``data/.gitignore`` and write the +meta information in ``data/data.xml.dvc``. Further information on the file +format of the ``*.dvc`` can be found under `DVC-File Format `_. -Um nun verschiedene Versionen eurer Projektdaten mit Git verwalten zu können, -müsst ihr jedoch nur die CVS-Datei hinzufügen: +In order to be able to manage different versions of your project data with Git, +you only have to add the CVS file: .. code-block:: console $ git add data/.gitignore data/fortune500.csv.dvc $ git commit -m "Add raw data to project" -Daten speichern und abrufen ---------------------------- +Store and retrieve data +----------------------- -Die Daten können vom Arbeitsverzeichnis eures Git-Repository auf den entfernten -Speicherplatz kopiert werden mit +The data can be copied from the working directory of your Git repository to the +remote storage space with .. code-block:: console $ dvc push -Falls ihr aktuellere Daten abrufen wollt, könnt ihr dies mit +If you want to call up more current data, you can do so with .. code-block:: console $ dvc pull -Importieren und Aktualisieren ------------------------------ +Import and update +----------------- -Ihr könnt auch Daten und Modelle eines anderen Projekts importieren mit dem -``dvc import``-Befehl, z.B.: +You can also import data and models from another project with the command ``dvc +import``, e.g.: .. code-block:: console $ dvc import https://github.com/iterative/dataset-registry get-started/data.xml Importing 'get-started/data.xml (https://github.com/iterative/dataset-registry)' -> 'data.xml' -Dies lädt die Datei aus der `dataset-registry -`_ in das aktuelle -Arbeitsverzeichnis, fügt sie ``.gitignore`` hinzu und erstellt -``data.xml.dvc``. +This loads the file from the `dataset-registry +`_ into the current working +directory, adds ``.gitignore`` and creates ``data.xml.dvc``. -Mit ``dvc update`` können wir diese Datenquellen aktualisieren bevor wir eine -Pipeline reproduzieren, die von diesen Datenquellen abhängt, z.B.: +With ``dvc update`` we can update these data sources before we reproduce a +pipeline that depends on these data sources, e.g. .. code-block:: console diff --git a/docs/productive/dvc/integration.rst b/docs/productive/dvc/integration.rst index e6e32c7a..cb66e5b3 100644 --- a/docs/productive/dvc/integration.rst +++ b/docs/productive/dvc/integration.rst @@ -1,11 +1,11 @@ -Vim- und IDE-Integration -======================== +Vim and IDE integration +======================= Vim --- -Um DVC-Dateien in Vim als YAML zu erkennen, solltet ihr Folgendes in -``~/.vimrc`` hinzufügen:: +To recognize DVC files in Vim as YAML, you should add the following in +``~/.vimrc``:: " DVC autocmd! BufNewFile,BufRead Dvcfile,*.dvc setfiletype yaml @@ -15,7 +15,6 @@ IntelliJ IDEs `intellij-dvc `_ -ist ein Plugin für IntelliJ IDEs einschließlich PyCharm, IntelliJ IDEA und -CLion. Es kann aus dem `JetBrains Plugins-Repository -`_ heruntergeladen -werden. +is a plugin for IntelliJ IDEs including PyCharm, IntelliJ IDEA and CLion. It can +be downloaded from the `JetBrains Plugins-Repository +`_. diff --git a/docs/productive/dvc/metrics.rst b/docs/productive/dvc/metrics.rst index 06331c68..695c6794 100644 --- a/docs/productive/dvc/metrics.rst +++ b/docs/productive/dvc/metrics.rst @@ -1,18 +1,17 @@ -Versuchsmetriken -================ +Trial metrics +============= -Mit dem `dvc metrics `_-Kommando -ist DVC auch ein Framework zum Erfassen und Vergleichen der Performance von -Experimenten. +With the `dvc metrics `_ +command, DVC is also a framework for recording and comparing the performance of +experiments. `evaluate.py `_ -berechnet den AUC (**A** rea **U** nder the **C** urve, deutsch `Fläche unter -der Kurve `_)-Wert. -Dabei verwendet es den Testdatensatz, ließt die Features aus ``features/test.pkl`` -und erstellt die Metrikdatei ``auc.metric``. Sie kann DVC als Metrik kenntlich -gemacht werden mit der ``-M``-Option von `dvc run -`_, in unserem Beispiel also mit: +calculates the AUC (**A** rea **U** nder the **C** urve). It uses the test data +set, reads the features from the file ``features/test.pkl`` and creates the +metrics file ``auc.metric``. It can be identified as a DVC metric with the +``-M`` option of `dvc run `_, in our +example with: .. code-block:: console @@ -31,16 +30,16 @@ gemacht werden mit der ``-M``-Option von `dvc run - auc.json: cache: false -Mit ``dvc metrics show`` lassen sich Experimente dann auch über verschiedene -Branches und Tags hinweg vergleichen: +With ``dvc metrics show`` experiments can be compared then through various +branches and tags: .. code-block:: console $ dvc metrics show auc.json: 0.514172 -Um nun unsere erste Version der DVC-Pipeline abzuschließen, fügen wir die -Dateien und ein Tag dem Git-Repository hinzu: +Now to complete our first version of the DVC pipeline, let's add the files and a +tag to the Git repository: .. code-block:: console diff --git a/docs/productive/dvc/params.rst b/docs/productive/dvc/params.rst index b5d0d02a..cc00c45b 100644 --- a/docs/productive/dvc/params.rst +++ b/docs/productive/dvc/params.rst @@ -1,8 +1,8 @@ -Parametrisierung +Parameterisation ================ -In der nächsten Phase unseres Beispiels parametrisieren wir die Verarbeitung -und erstellen hierfür die Datei ``params.yaml`` mit folgendem Inhalt: +In the next phase of our example, we parameterise the processing and create the +file ``params.yaml`` with the following content: .. code-block:: yaml @@ -11,20 +11,20 @@ und erstellen hierfür die Datei ``params.yaml`` mit folgendem Inhalt: lo: 1 hi: 2 -Damit die Parameter gelesen werden, wird dem ``dvc run``-Befehl noch ``-p -:`` hinzugefügt, also in unserem Beispiel: +To read the parameters, the option ``-p :`` must be added +to the ommand ``dvc run``, in our example: .. code-block:: console - $ dvc run -n featurize -d src/featurization.py -d data/splitted \ + $ dvc run -n featurise -d src/featurisation.py -d data/splitted \ -p params.yaml:max_features,ngram_range.lo,ngram_range.hi -o data/features \ - python src/featurization.py data/splitted data/features + python src/featurisation.py data/splitted data/features -Dies ergänzt die ``dvc.yaml``-Datei um: +This adds to the ``dvc.yaml`` file: .. code-block:: yaml - featurize: + featurise: cmd: python src/featurization.py data/splitted data/features deps: - data/splitted @@ -36,17 +36,17 @@ Dies ergänzt die ``dvc.yaml``-Datei um: outs: - data/features -Damit diese Phase wiederholt werden kann, werden die hd5-Hashwerte und -Parameterwerte in der ``dvc.lock``-Datei gespeichert: +So that this phase can be repeated, the hd5 hash values and parameter values are +stored in the file ``dvc.lock``: .. code-block:: yaml - featurize: - cmd: python src/featurization.py data/splitted data/features + featurise: + cmd: python src/featurisation.py data/splitted data/features deps: - path: data/splitted md5: 1ce9051bf386e57c03fe779d476d93e7.dir - - path: src/featurization.py + - path: src/featurisation.py md5: a56570e715e39134adb4fdc779296373 params: params.yaml: @@ -54,8 +54,8 @@ Parameterwerte in der ``dvc.lock``-Datei gespeichert: ngram_range.hi: 2 ngram_range.lo: 1 -Schließlich müssen noch ``dvc.lock``, ``dvc.yaml`` und ``data/.gitignore`` im -Git-Repository aktualisiert werden: +Finally ``dvc.lock``, ``dvc.yaml`` and ``data/.gitignore`` in the Git repository +need to be updated: .. code-block:: console diff --git a/docs/productive/dvc/pipeline.rst b/docs/productive/dvc/pipeline.rst index 0e0b7832..5d10f9e7 100644 --- a/docs/productive/dvc/pipeline.rst +++ b/docs/productive/dvc/pipeline.rst @@ -1,26 +1,25 @@ Pipelines ========= -Code und Daten verbinden ------------------------- +Connect code and data +--------------------- -Befehle wie ``dvc add``, ``dvc push`` und ``dvc pull`` können unabhängig von -Änderungen im Git-Repository vorgenommen werden und bieten daher nur die Basis -um große Datenmengen und Modelle zu verwalten. Um tatsächlich reproduzierbare -Ergebnisse zu erzielen, müssen Code und Daten miteinander verbunden werden. +Commands like ``dvc add``, ``dvc push`` and ``dvc pull`` can be made +independently of changes in the Git repository and therefore only provide the +basis for managing large amounts of data and models. In order to actually +achieve reproducible results, code and data must be linked together. .. figure:: combine-git-dvc.png - :alt: Git und DVC verbinden + :alt: Connect Git and DVC Design: André Henze, Berlin -Mit ``dvc run`` könnt Ihr einzelne Verbeitungsstufen erstellen, wobei jede -Stufe durch eine, mit Git verwaltete, Quellcode-Datei sowie weiteren -Abhängigkeiten und Ausgabedaten beschrieben wird. Alle Stufen zusammen bilden -dann die DVC-Pipeline. +With ``dvc run`` you can create individual processing levels, each level being +described by a source code file managed with Git as well as other dependencies +and output data. All stages together then form the DVC pipeline. -In unserem Beispiel `dvc-example `_ soll -die erste Stufe die Daten in Trainings- und Testdaten aufteilen: +In our example `dvc-example `_, the first +stage is to split the data into training and test data: .. code-block:: console @@ -28,19 +27,18 @@ die erste Stufe die Daten in Trainings- und Testdaten aufteilen: python src/split.py data/data.xml ``-n`` - gibt den Namen der Verarbeitungsstufe an. + indicates the name of the processing stage. ``-d`` - gibt Abhängigkeiten (*dependencies*) für das reproduzierbare Kommando an. + dependencies on the reproducible command. - Wenn zum Reproduzieren der Ergebnisse beim nächsten Mal ``dvc repo`` - aufgerufen wird, überprüft DVC diese Abhängigkeiten und entscheidet, ob - diese auf dem aktuellen Stand sond oder erneut ausgeführt werden müssen um - aktuellere Ergebnisse zu erhalten. + The next time ``dvc repo`` is called to reproduce the results, DVC checks + these dependencies and decides whether they need to be updated or run again + to get more current results. ``-o`` - gibt die Ausgabedatei oder das Ausgabeverzeichnis an. + specifies the output file or directory. -In unserem Fall sollte sich der Arbeitsbereich geändert haben in: +In our case, the work area should have changed to: .. code-block:: console @@ -57,7 +55,7 @@ In unserem Fall sollte sich der Arbeitsbereich geändert haben in: └── src └── split.py -Die generierte ``dvc.yaml``-Datei sieht dann z.B. folgendermaßen aus: +The generated ``dvc.yaml`` file looks like this, for example: .. code-block:: yaml @@ -70,16 +68,15 @@ Die generierte ``dvc.yaml``-Datei sieht dann z.B. folgendermaßen aus: outs: - data/splitted -Da die Daten im Ausgabeverzeichnis nie mit Git versioniert werden sollten, hat -``dvc run`` dies auch bereits die ``data/.gitignore``-Datei geschrieben: +Since the data in the output directory should never be versioned with Git, ``dvc +run`` has already written the file ``data/.gitignore``: .. code-block:: console /data.xml + /splitted -Anschließend müssen die geänderten Daten nur noch in Git bzw. DVC übernommen -werden: +Then the changed data only has to be transferred to Git or DVC: .. code-block:: console @@ -87,6 +84,6 @@ werden: $ git commit -m "Create split stage" $ dvc push -Werden nun mehrere Phasen mit ``dvc run`` erstellt, wobei die Ausgabe eines -Kommandos als Abhängigkeit eines anderen angegeben wird, entsteht eine `DVC -Pipeline `_. +If several phases are now created with ``dvc run`` and the output of one command +being specified as a dependency of another, a `DVC Pipeline +`_ is created. diff --git a/docs/productive/dvc/reproduce.rst b/docs/productive/dvc/reproduce.rst index 4942b109..36c263ab 100644 --- a/docs/productive/dvc/reproduce.rst +++ b/docs/productive/dvc/reproduce.rst @@ -1,8 +1,7 @@ -Reproduzieren -============= +Reproduce +========= -Um die Ergebnisse eines Projekts zu reproduzieren, clonen wir rufen -anschließend die mit DVC verwalteten Daten ab: +To reproduce the results of a project, we first clone the data managed with DVC: .. code-block:: console @@ -14,7 +13,7 @@ anschließend die mit DVC verwalteten Daten ab: $ ls data/ data.xml data.xml.dvc -Anschließend könnt ihr die Ergebnisse einfach reproduzieren mit `dvc repro +Then you can easily reproduce the results with `dvc repro `_: .. code-block:: console @@ -26,8 +25,8 @@ Anschließend könnt ihr die Ergebnisse einfach reproduzieren mit `dvc repro Stage 'train' didn't change, skipping Stage 'evaluate' didn't change, skipping -Ihr könnt nun z.B. Parameter in der ``params.yaml``-Datei ändern und -anschließend die Pipeline erneut durchlaufen: +You can now, for example, change parameters in the ``params.yaml`` file and then +run through the pipeline again: .. code-block:: console @@ -42,7 +41,6 @@ anschließend die Pipeline erneut durchlaufen: To track the changes with git, run: git add dvc.lock -In unserem Fall hatte die Änderung der Parameter also keinen Einfluss auf das -Ergebnis. Beachtet dabei jedoch, dass DVC Änderungen an Abhängigkeiten und -Ausgaben über md5-Hashwerte erkennt, die in der ``dvc.lock``-Datei gespeichert -sind. +In our case, changing the parameters had no effect on the result. Please note, +that DVC recognises changes to dependencies and outputs via md5 hash values in +``dvc.lock``. diff --git a/docs/productive/envs/devpi.rst b/docs/productive/envs/devpi.rst index 70211885..ce9cc456 100644 --- a/docs/productive/envs/devpi.rst +++ b/docs/productive/envs/devpi.rst @@ -1,5 +1,5 @@ devpi ===== -`devpi `_ ist ein PyPI-Server, der die Paketierung, das -Testen und Veröffentlichen von Python-Paketen vereinfacht. +`devpi `_ is a PyPI server that simplifies the packaging, +testing and publishing of Python packages. diff --git a/docs/productive/envs/glossary.rst b/docs/productive/envs/glossary.rst index fbda034d..ba9fb559 100644 --- a/docs/productive/envs/glossary.rst +++ b/docs/productive/envs/glossary.rst @@ -1,27 +1,26 @@ -Glossar -======= +Glossary +======== .. glossary:: - Built Distribution - Eine Struktur aus Dateien und Metadaten, die bei der Installation nur an den - richtigen Speicherort auf dem Zielsystem verschoben werden müssen. - :term:`Wheel` ist ein solches Format, nicht jedoch *distutil’s* - :term:`Source Distributions `, die einen - Build-Schritt erfordern. + built distribution + A structure of files and metadata that only needs to be moved to the + correct location on the target system during installation. :term:`wheel` + is such a format, but not *distutil’s* :term:`source distributions + ` that require a build step. conda - Paketmanagement-Tool für die `Anaconda - `_-Distribution von - `Continuum Analytics `_. Sie ist speziell - auf die wissenschaftliche Gemeinschaft ausgerichtet, insbesondere auf - Windows, wo die Installation von binären Erweiterungen oft schwierig ist. - - Conda installiert keine Pakete von PyPI und kann nur von den offiziellen - Continuum-Repositories oder von `anaconda.org `_ - oder lokalen (z.B. Intranet-) Paketservern installieren. Beachtet jedoch, - dass Pip in conda installiert werden und Seite an Seite arbeiten kann, um - Distributionen von PyPI zu verwalten. + Package management tool for the `Anaconda + `_ distribution from + `Continuum Analytics `_. It’s specifically + aimed at the scientific community, particularly Windows, where installing + binary extensions is often difficult. + + Conda does not install packages from PyPI and can only install from the + official Continuum repositories or from `anaconda.org + `_ or local ( e.g. intranet) package servers. + Note, however, that Pip can be installed in conda and can work side by + side to manage distributions of PyPI. .. seealso:: * `Conda: Myths and Misconceptions @@ -30,68 +29,66 @@ Glossar `_ devpi - `devpi `_ ist ein leistungsstarker PyPI-kompatibler - Server und ein PyPI-Proxy-Cache mit einem Befehlszeilenwerkzeug um - Paketierungs-, Test- und Veröffentlichungsaktivitäten zu ermöglichen. - - Distribution Package - Eine versionierte Archivdatei, die Python-:term:`Pakete `, - -:term:`Module ` und andere Ressourcendateien enthält, die zum - Verteilen eines :term:`Releases ` verwendet werden. - - Egg - Ein :term:`Built Distribution`-Format, das von :term:`Setuptools` - eingeführt wurde und nun durch :term:`Wheel` ersetzt wird. Weitere - Informationen findet ihr unter `The Internal Structure of Python Eggs - `_ und `Python + `devpi `_ is a powerful PyPI compatible server and + PyPI proxy cache with a command line tool to enable packaging, testing + and publishing activities. + + distribution package + A versioned archive file that contains Python :term:`packages `, :term:`modules `, and other resource files used to + distribute a :term:`release`. + + egg + A :term:`built distribution` format introduced by :term:`setuptools` + that is now being replaced by :term:`wheel`. For more information, see + `The Internal Structure of Python Eggs + `_ and `Python Eggs `_. - Import Package - Ein Python-Modul, das andere Module oder rekursiv andere Pakete enthalten - kann. + import package + A Python module that can contain other modules or recursively other + packages. - Modul - Die Grundeinheit der Wiederverwendbarkeit von Code in Python, die in - einem von zwei Typen existiert: + module + The basic unit of code reusability in Python, which exists in one of two + types: - Pure Module - Ein Modul, das in Python geschrieben wurde und in einer einzigen - ``.py``-Datei enthalten ist (und möglicherweise zugehörigen - ``.pyc``- und/oder ``.pyo``-Dateien). + pure module + A module written in Python contained in a single ``.py`` file (and + possibly associated ``.pyc``- and/or ``.pyo`` files). - Extension Module - In der Regel in eine einzelne dynamisch ladbare vorkompilierte - Datei, z. B. einer gemeinsamen Objektdatei (``.so``). + extension module + Usually a single dynamically loadable precompiled file, e.g. a common + object file (``.so``). pip - Ein Tool zum Installieren von Python-Paketen. + A tool for installing Python packages. `Docs `_ | `GitHub `_ | `PyPI `_ | Pipfile - Anwendungsfreundliche, auf `TOML `_ - basierende Alternative zur ``requirements.txt``-Datei von pip. + User-friendly, on `TOML `_ based + alternative to the ``requirements.txt`` file of pip. - Dabei kann unterschieden werden zwischen zwei verschiedenen Gruppen von - Paketen: ``[packages]`` und ``[dev-packages]``. + A distinction can be made between two different groups of packages: + ``[packages]`` and ``[dev-packages]``. `GitHub `_ Pipfile.lock - Maschinenlesbare Datei auf Basis von `JSON - `_, die alle transitiven - Abhängigkeiten mit deren exakten Versionen und Download-Hashes enthält. + Machine-readable file based on `JSON + `_ that contains all transitive + dependencies with their exact versions and download hashes. - Auch Pipfile.lock unterscheidet zwischen ``[packages]`` und + Pipfile.lock also differentiates between ``[packages]`` and ``[dev-packages]``. Pipenv - Pipenv ist ein Projekt, das darauf abzielt, die beste aller - Verpackungswelten in die Python-Welt zu bringen. Es vereint - :term:`pipfile`, :term:`pip` und :term:`virtualenv ` - in einer einzigen Toolchain. + Pipenv is a project that aims to bring the best of all packaging worlds + to the Python world. It combines :term:`pipfile`, :term:`pip` and + :term:`virtualenv` in a single toolchain. `Docs `_ | `GitHub `_ | @@ -99,46 +96,44 @@ Glossar pypi.org - `pypi.org `_ ist der Domainname für den - Python Package Index (PyPI). Er löste 2017 den alten Index-Domain-Namen - *pypi.python.org* ab. Er wird von :term:`warehouse` unterstützt. + `pypi.org `_ is the domain name for the Python + Package Index (PyPI). In 2017 it replaced the old index domain name + *pypi.python.org*. He is supported by :term:`warehouse`. Python Package Index (PyPI) - `PyPI `_ ist der Standard-Paket-Index für die - Python-Community. Alle Python-Entwickler können ihre Distributionen nutzen - und verteilen. + `PyPI `_ is the standard package index for the Python + community. All Python developers can use and distribute their + distributions. - Release - Der Snapshot eines Projekts zu einem bestimmten Zeitpunkt, gekennzeichnet - durch eine Versionskennung. + release + The snapshot of a project at a specific point in time, identified by a + version identifier. - Eine Veröffentlichung kann mehrere :term:`Built Distributions - ` zur Folge haben. + One release can result in several :term:`Built Distributions + `. setuptools - setuptools (und ``easy_install``) ist eine Sammlung von Verbesserungen der - Python-Distutils, mit denen ihr Python-Distributionen einfacher erstellen - und verteilen könnt, insbesondere solche, die Abhängigkeiten von anderen - Paketen haben. + setuptools (and ``easy_install``) is a collection of improvements to the + Python Distutils that make it easier to create and distribute Python + distributions, especially those that have dependencies on other packages. - Source Distribution (sdist) - Ein Verteilungsformat (das normalerweise mithilfe von ``python setup.py - sdist`` generiert wird). + source distribution (sdist) + A distribution format (typically generated using) ``python setup.py + sdist``. - Es stellt Metadaten und die wesentlichen Quelldateien bereit, die für - die Installation mit einem Tool wie :term:`Pip` oder zum Generieren - von :term:`Built Distributions ` benötigt werden. + It provides metadata and the essential source files required for + installation with a tool like :term:`Pip` or for generating :term:`built + distributions `. Spack - Ein flexibler Paketmanager, der mehrere Versionen, Konfigurationen, - Plattformen und Compiler unterstützt. Spack ist ähnlich wie der `Nix - `_-Paketmanager, ermöglicht jedoch die Definition - virtueller Abhängigkeiten und bietet eine Syntax zur Parametrisierung. Die - Pakete sind in Python geschrieben, um einen einfachen Austausch von - Compilern, Bibliotheksversionen, Build-Optionen usw. zu ermöglichen. Es - können beliebig viele Versionen von Paketen gleichzeitig auf demselben - System existieren. Spack wurde für den raschen Aufbau wissenschaftlicher - Anwendungen auf Clustern und Supercomputern entwickelt. + A flexible package manager that supports multiple versions, + configurations, platforms, and compilers. Spack is similar to the `Nix + `_ package manager, but allows the definition of + virtual dependencies and offers a syntax for parameterisation. The + packages are written in Python for easy exchange of compilers, library + versions, build options, etc. Any number of versions of packages can + coexist on the same system. Spack was developed for rapidly building + scientific applications on clusters and supercomputers. `Docs `_ | `GitHub `_ | @@ -146,27 +141,27 @@ Glossar `The Spack package manager: bringing order to HPC software chaos `_ | - Virtuelle Umgebung - Eine isolierte Python-Umgebung, die die Installation von Paketen für eine - bestimmte Anwendung ermöglicht, anstatt sie systemweit zu installieren. + virtualenv + An isolated Python environment that allows packages to be installed for a + specific application rather than installing them system-wide. `Docs `_ | `Creating Virtual Environments `_ | Warehouse - Die aktuelle Codebasis, die den Python Package Index (PyPI) antreibt. Sie - wird auf `pypi.org`_ gehostet. - - Wheel - Distributionsformat, das mit `PEP 427 - `_ eingeführt wurde. Es soll das - :term:`Egg`-Format ersetzen und wird von aktuellen - :term:`Pip`-Installationen unterstützt. - - C-Erweiterungen können als plattformspezifische Wheels für Windows, Mac OS - und Linux auf PyPI bereitgestellt werden. Dies hat für die Benutzer des - Pakets den Vorteil, bei der Installation nicht kompilieren zu müssen. + The current code base that powers the Python Package Index (PyPI). It is + hosted on `pypi.org`_. + + wheel + Distribution format introduced with `PEP 427 + `_. It is intended to replace + the :term:`Egg` format and is supported by current :term:`pip` + installations. + + C extensions can be provided as platform-specific wheels for Windows, Mac + OS and Linux on PyPI. This has the advantage for the users of the package + that they don’t have to compile during the installation. `Home `_ | `Docs `_ | diff --git a/docs/productive/envs/index.rst b/docs/productive/envs/index.rst index c77bc118..be56259d 100644 --- a/docs/productive/envs/index.rst +++ b/docs/productive/envs/index.rst @@ -1,12 +1,11 @@ -Umgebungen reproduzieren -======================== +Reproduce environments +====================== -Führt die Notebooks in einer dezidierten Umgebung aus (z.B. mit -:doc:`pipenv/index`, :doc:`devpi` und :doc:`Spack `. Speichert -die Dateien mit den Spezifikationen, also z.B. ``Pipfile``, ``Pipfile.lock``, -``package-lock.json`` etc. Auf diese Weise könnt ihr und andere eure -Berechnungen reproduzieren und auch das Deployment in die Produktionsumgebung -wird vereinfacht. +Run the notebook in a dedicated environment (e.g. with :doc:`pipenv/index`, +:doc:`devpi` and :doc:`Spack `. Save the file with the +specifications, e.g. ``Pipfile``, ``Pipfile.lock``, ``package-lock.json`` etc. +In this way, you and others can reproduce your calculations and deployment into +the production environment is simplified. .. toctree:: :hidden: diff --git a/docs/productive/envs/pipenv/deterministic.rst b/docs/productive/envs/pipenv/deterministic.rst index 6d5bbe43..24dd93c8 100644 --- a/docs/productive/envs/pipenv/deterministic.rst +++ b/docs/productive/envs/pipenv/deterministic.rst @@ -1,10 +1,10 @@ -Deterministische Builds +Deterministic builds ======================= -Ihr müsst nur spezifizieren, was ihr wollt: +All you have to do is specify what you want: -Mit ``pipenv install requests`` wird z.B. ein ``Pipfile`` erzeugt wie das -folgende: +For example, ``pipenv install requests`` creates a ``Pipfile`` like the +following: .. code-block:: ini @@ -21,7 +21,8 @@ folgende: [requires] python_version = "3.6" -Die zugehörige ``Pipfile.lock``-Datei spezifiziert jedoch die Pakete exakt, z.B.: +However, the associated ``Pipfile.lock`` file specifies the packages exactly, +for example: .. code-block:: json @@ -47,6 +48,6 @@ Die zugehörige ``Pipfile.lock``-Datei spezifiziert jedoch die Pakete exakt, z.B "develop": {} } -``Pipfile.lock`` spezifiziert auch alle Abhängigkeiten eures Projekts, wobei die -Hashwerte der heruntergeladenen Dateien gespeichert werden. Dies soll -wiederholbare und deterministische Builds gewährleisten. +``Pipfile.lock`` also specifies all the dependencies of your project, whereby +the hash values of the downloaded files are saved. This is to ensure repeatable +and deterministic builds. diff --git a/docs/productive/envs/pipenv/index.rst b/docs/productive/envs/pipenv/index.rst index 6c231450..a1f250af 100644 --- a/docs/productive/envs/pipenv/index.rst +++ b/docs/productive/envs/pipenv/index.rst @@ -2,9 +2,9 @@ Pipenv ====== -`Pipenv `_ ist ein Python-Paketmanager. Er nutzt -:term:`Pip` zum Installieren von Python-Paketen, vereinfacht jedoch auch die -Verwaltung und Pflege von Abhängigkeiten. +`Pipenv `_ is a Python package manager. He uses +:term:`Pip` to install Python packages, but also simplifies the management and +maintenance of dependencies. .. toctree:: :hidden: diff --git a/docs/productive/envs/pipenv/install.rst b/docs/productive/envs/pipenv/install.rst index 141f171a..c7d21399 100644 --- a/docs/productive/envs/pipenv/install.rst +++ b/docs/productive/envs/pipenv/install.rst @@ -1,16 +1,15 @@ Installation ============ -Dieser Abschnitt behandelt die Grundlagen zur Installation von -:term:`Python-Paketen `. +This section covers the basics of installing :term:`Python packages +`. -Voraussetzungen für die Installation von Paketen ------------------------------------------------- +Requirements for installing packages +------------------------------------ -Vor der Installation von Python-Paketen müssen einige Voraussetzungen erfüllt -sein. +Before installing Python packages, a few prerequisites must be met. -#. Stellt sicher, dass ihr die gewünschte Python-Version verwendet: +#. Make sure you are using the version of Python you want: .. code-block:: console @@ -18,8 +17,7 @@ sein. Python 3.6.3 .. note:: - In iPython oder einem Jupyter Notebook könnt ihr die Version - folgendermaßen herausbekommen: + In iPython or a Jupyter Notebook you can find out the version with: .. code-block:: ipython @@ -28,40 +26,38 @@ sein. Python 3.6.3 .. note:: - Falls ihr das System-Python eurer Linux-Distribution verwendet, solltet - ihr zunächst eine virtuelle Umgebung mit Python 3 und :term:`Pip ` - erstellen. + If you use the system Python of your Linux distribution, you should + first create a virtual environment with Python 3 and :term:`Pip `. -#. Stellt sicher, dass :term:`Pip ` installiert ist: +#. Make sure :term:`Pip ` :is installed: .. code-block:: console $ pip --version pip 10.0.1 - #. Falls Pip noch nicht installiert ist, könnt ihr es installieren (lassen) + #. If Pip is not yet installed, you can install it - * für Python 2 mit: + * for Python 2 with: .. code-block:: console $ sudo apt install python-pip - * für Python 3 mit: + * for Python 3 with: .. code-block:: console $ sudo apt install python3-venv python3-pip -Pipenv installieren -------------------- +nstall Pipenv +------------- -:term:`pipenv` ist ein Abhängigkeitsmanager für Python-Projekte. Er nutzt -:term:`Pip` zum Installieren von Python-Paketen, er vereinfacht jedoch die -Verwaltung von Abhängigkeiten. Pip kann zum Installieren von Pipenv verwendet -werden, es sollte jedoch das ``--user``-Flag verwendet werden, damit es nur -für diesen Nutzer bereitsteht. Dadurch soll verhindert werden, dass -versehentlich systemweite Pakete überschrieben werden: +:term:`pipenv` is a dependency manager for Python projects. It to install Python +packages, but it simplifies dependency management. Pip can be used to install +Pipenv, but the ``--user`` flag should be used so that it is only available to +that user. This is to prevent system-wide packages from being accidentally +overwritten: .. code-block:: console @@ -75,42 +71,41 @@ versehentlich systemweite Pakete überschrieben werden: .. note:: - Wenn pipenv nach der Installation nicht in der Shell verfügbar ist, muss - ggf. das ``USER_BASE/bin``-Verzeichnis in ``PATH`` angegeben werden. + If pipenv is not available in the shell after the installation, the + ``USER_BASE/bin`` directory may have to be specified in ``PATH``. - * Unter Linux und MacOS lässt sich ``USER_BASE`` ermitteln mit:: + * On Linux and MacOS the ``USER_BASE`` can be determined with: $ python3 -m site --user-base /Users/veit/.local - Anschließend muss noch das ``bin``-Verzeichnis angehängt und zu ``PATH`` - hinzugefügt werden. Alternativ kann ``PATH`` dauerhaft gesetzt werden, indem - ``~/.profile`` oder ``~/.bash_profile`` geändert werden, in meinem Fall also:: + Then the ``bin`` directory must be appended and added to ``PATH``. + Alternatively, ``PATH`` can be set permanently by changing ``~/.profile`` + or ``~/.bash_profile``, in my case:: export PATH=/Users/veit/.local/bin:$PATH - * Unter Windows kann das Verzeichnis ermittelt werden mit - ``py -m site --user-site`` und anschließend ``site-packages`` durch - ``Scripts`` ersetzt werden. Dies ergibt dann z.B.: + * On Windows, the directory can be determined with ``py -m site --user-site`` + and then ``site-packages`` can be replaced by ``Scripts``. his then gives, + for example: .. code-block:: console C:\Users\veit\AppData\Roaming\Python36\Scripts - Um dauerhaft zur Verfügung zu stehen, kann dieser Pfad unter ``PATH`` - im Control Panel eingetragen werden. + In order to be permanently available, this path can be entered in ``PATH`` + in the control panel -Weitere Informationen zur nutzerspezifischen Installation findet ihr in `User +Further information on user-specific installations can be found in `User Installs `_. -Virtuelle Umgebungen erstellen ------------------------------- +Create virtual environments +--------------------------- -:term:`Virtuelle Python-Umgebungen ` ermöglichen die -Installation von Python-Paketen an einem isolierten Ort für eine bestimmte -Anwendung, anstatt sie global zu installieren. Ihr habt also eure eigenen -Installationsverzeichnisse und teilt keine Bibliotheken mit anderen -virtuellen Umgebungen: +:term:`Python virtual environments ` allow Python packages +to be installed in an isolated location for a specific application, rather than +installing them globally. So you have your own installation directories and do +not share libraries with other virtual environments: .. code-block:: console diff --git a/docs/productive/envs/pipenv/spack.rst b/docs/productive/envs/pipenv/spack.rst index ea57e288..319452b3 100644 --- a/docs/productive/envs/pipenv/spack.rst +++ b/docs/productive/envs/pipenv/spack.rst @@ -1,15 +1,14 @@ -Pipenv und Spack +Pipenv and Spack ================ -Pipenv wurde bereits zur :doc:`Installation von Jupyter Notebooks -` verwendet. Wir benötigen hier jedoch Pipenv für unsere -:doc:`Spack Environments <../../envs/spack/envs>` um -einerseits binärkompatible Builds mit Spack erzeugen zu können und andererseits -Python-Pakete für die Datenerhebung, -Visualisierung etc. einfach nutzen zu -können. +Pipenv has already been used to :doc:`install Jupyter notebooks +`. However, we need Pipenv for our :doc:`Spack +environments <../../envs/spack/envs>` to be able to generate binary-compatible +builds with Spack on the one hand and to be able to easily use Python packages +for data collection, visualization, etc. on the other. -Aktiviert hierfür zunächst die passende Python-Version aus dem -Spack-Environment: +To do this, first activate the appropriate Python version from the Spack +environment: .. code-block:: console @@ -19,7 +18,7 @@ Spack-Environment: $ which python /Users/veit/jupyter-tutorial/spackenvs/python-374/.spack-env/view/bin/python -Das bestehende Pipenv-Environment könnt ihr anschließend installieren mit: +Then you can install the existing Pipenv environment with: .. code-block:: console @@ -31,8 +30,7 @@ Das bestehende Pipenv-Environment könnt ihr anschließend installieren mit: Using /Users/veit/jupyter-tutorial/spackenvs/python-374/.spack-env/view/bin/python3.7 (3.7.4) to create virtualenv… … -Dies verwendet das mit Spack installierte Environment und installiert weitere -Pakete. +This uses the environment installed with Spack and installs additional packages. .. seealso:: diff --git a/docs/productive/envs/pipenv/use.rst b/docs/productive/envs/pipenv/use.rst index b7d6feb7..5d40ca46 100644 --- a/docs/productive/envs/pipenv/use.rst +++ b/docs/productive/envs/pipenv/use.rst @@ -1,13 +1,12 @@ -Nutzung -======= +Usage +===== -Beispiel --------- +Example +------- -Nachdem nun ``requests`` installiert ist, kann es verwendet werden. +Now that ``requests`` is installed, it can be used. -#. Exemplarisch legen wir hierfür die Datei ``main.py`` mit folgendem Inhalt - an: +#. As an example, we create the file ``main.py`` with the following content: .. code-block:: python @@ -17,19 +16,19 @@ Nachdem nun ``requests`` installiert ist, kann es verwendet werden. print(response.status_code) -#. Anschließen kann das Skript ausgeführt werden mit: +#. Then the script can be executed with: .. code-block:: console $ pipenv run python main.py -#. Als Ergebnis des Aufrufs solltet ihr den HTTP-Status-Code ``200`` erhalten. +#. As a result of the call you should receive the HTTP status code ``200``. -Die Verwendung von ``pipenv run`` stellt sicher, dass eure installierten Pakete -für Ihr Skript verfügbar sind. +Using ``pipenv run`` ensures that your installed packages are available for your +script. -Alternativ könnt ihr euch auch eine neue Shell mit ``pipenv shell`` erstellen, -mit der auf alle installierten Pakete zugegriffen werden kann: +Alternatively, you can also create a new shell ``pipenv shell`` with which all +installed packages can be accessed: .. code-block:: console @@ -37,56 +36,55 @@ mit der auf alle installierten Pakete zugegriffen werden kann: Launching subshell in virtual environment… bash-4.3.30$ . /Users/veit/.local/share/virtualenvs/myproject-9TTuTZjx/bin/activate -Optionen --------- +Options +------- ``-venv`` - gibt den Pfad zum Virtualenv an, üblicherweise in - ``~/.local/share/virtualenvs/``. Falls ihr jedoch ein Verzeichnis - ``myproject/.venv`` angelegt habt, verwendet ``pipenv`` diesen Ordner um - dort die zugehörige Python-Umgebung anzulegen. + specifies the path to the Virtualenv, usually in + ``~/.local/share/virtualenvs/``. However, if you have created a directory + ``myproject/.venv``, ``pipenv`` use this folder to create the associated + Python environment there. ``--py`` - gibt den Pfad zum Python-Interpreter an. + specifies the path to the Python interpreter. ``--envs`` - gibt Optionen der Environment-Variablen aus. + outputs options of the environment variables. - Für ``PIPENV_DONT_LOAD_ENV``, ``PIPENV_DONT_USE_PYENV`` und - ``PIPENV_DOTENV_LOCATION`` siehe :doc:`env`. + For ``PIPENV_DONT_LOAD_ENV``, ``PIPENV_DONT_USE_PYENV`` and + ``PIPENV_DOTENV_LOCATION`` see :doc:`env`. - Wenn ihr diese Umgebungsvariablen pro Projekt festlegen möchtet, könnt ihr - `direnv `_ verwenden. + If you want to set these environment variables per project, you can use + `direnv `_. - Beachtet auch, dass pip selbst Umgebungsvariablen unterstützt, falls ihr - zusätzliche Anpassungen benötigt: `Pip Environment Variables + Also note that pip itself supports environment variables in case you need + additional adjustments: `Pip Environment Variables `_. - Hier noch ein Beispiel: + Here is another example: .. code-block:: console $ PIP_INSTALL_OPTION="-- -DCMAKE_BUILD_TYPE=Release" pipenv install -e . - Weitere Informationen hierzu findet ihr unter - `Configuration With Environment Variables + Further information can be found at `Configuration With Environment + Variables `_ ``--three``, ``--two``, ``--python`` - verwendet Python 2 oder Python 3 oder ein spezifisches Python, zu dem der - Pfad angegeben wird. + uses Python 2 or Python 3 or a specific Python to which the path is given. ``--site-packages`` - aktiviert site packages für das virtual environment. + enables site packages for the virtual environment. ``--pypi-mirror`` - gibt einen PyPI-Mirror an. Der Standard ist der - :term:`Python Package Index (PyPI)`. + indicates a PyPI mirror. The standard is the :term:`Python Package Index + PyPI)`. - Ihr könnt jedoch auch eure eigenen Mirror angeben: + However, you can also specify your own mirrors: - * mit der Umgebungsvariablen ``PIPENV_PYPI_MIRROR`` - * in der Kommandozeile, z.B. mit: + * with the environment variable ``PIPENV_PYPI_MIRROR`` + * in the command line, e.g. with: .. code-block:: console @@ -94,7 +92,7 @@ Optionen $ pipenv update --pypi-mirror https://pypi.cusy.io/simple … - * oder im ``pipfile``: + * or in ``pipfile``: .. code-block:: ini @@ -116,20 +114,19 @@ Optionen records = "*" .. note:: - Wird ein privater Index verwendet, kommt es aktuell noch zu Problemen - mit dem Hashing der Pakete. + If a private index is used, there are currently still problems with + hashing the packages. - Weitere Optionen findet ihr unter `pipenv - `_. + You can find more options at `pipenv `_. ``check`` --------- -``pipenv check`` prüft auf Sicherheitslücken und auf `PEP 508 -`_-Marker im Pipfile. Hierzu -verwendet es `safety `_. +``pipenv check`` checks for security holes and for `PEP 508 +` markers in the pipfile. For this it +uses `safety `_. -Beispiel: +Example: .. code-block:: console @@ -172,19 +169,16 @@ Beispiel: hardened for production use and should be used only as a development aid. .. note:: - ``pipenv`` bettet hierfür einen API-Clientschlüssel von ``pyup.io`` ein, - anstatt eine vollständige Kopie der CC-BY-NC-SA lizenzierten Datenbank - aufzunehmen. + ``pipenv`` embeds an API client key from ``pyup.io``, instead of including a + full copy of the CC-BY-NC-SA licensed database. -Um nun die vollständige Datenbank zu installieren könnt ihr -diese auschecken mit: +In order to install the complete database you can check it out with: .. code-block:: console $ pipenv install -e git+https://github.com/pyupio/safety-db.git#egg=safety-db -Um die lokale Datenbank zu verwenden, müsst ihr den Pfad zu dieser Datenbank -angeben, in meinem Fall also: +To use the local database, you have to enter the path to this database, in my case: .. code-block:: console @@ -213,23 +207,22 @@ angeben, in meinem Fall also: ``clean`` --------- -``pipenv clean`` deinstalliert alle Pakete, die nicht in ``Pipfile.lock`` -angegeben sind. +``pipenv clean`` uninstalls all packages not specified in ``Pipfile.lock``. ``graph`` --------- -``pipenv graph`` zeigt für die aktuell installierten Pakete die -Abhängigkeitsgrapheninformationen an. +``pipenv graph`` displays the dependency graph information for the currently +installed packages. ``install`` ----------- -``pipenv install`` installiert bereitgestellte Pakete und fügt sie dem Pipfile -hinzu. ``pipenv install`` kennt die folgenden Optionen: +``pipenv install`` installs the provided packages and adds them to the pipfile. +``pipenv install`` knows the following options: ``-d``, ``--dev`` - installiert die Pakete in ``[dev-packages]``, z.B.: + installs the packages in ``[dev-packages]``, for example: .. code-block:: console @@ -241,81 +234,79 @@ hinzu. ``pipenv install`` kennt die folgenden Optionen: pytest = "*" ``--deploy`` - bricht ab, wenn ``Pipfile.lock`` nicht aktuell ist oder eine falsche - Python-Version verwendet wird. + aborts if ``Pipfile.lock`` is out of date or an incorrect Python version is + used. ``-r``, ``--requirements`` ```` - importiert eine ``requirements.txt``-Datei + imports a ``requirements.txt`` file. ``--sequential`` - installiert die Abhängigkeit in einer bestimmten Reihenfolge, nicht - gleichzeitig. + installs the dependency in a specific order, not at the same time. - Dies verlangsamt zwar die Installation, erhöht jedoch die Determinierbarkeit - der Builds. + While this slows down the installation, it increases the determinability of + the builds. ``sdist`` vs. ``wheel`` ~~~~~~~~~~~~~~~~~~~~~~~ -Pip kann sowohl Pakete als :term:`Source Distribution (sdist)` oder -:term:`Wheel` installieren. Wenn beide auf PyPI vorhanden sind, wird pip ein -kompatibles :term:`Wheel` bevorzugen. +Pip can install packages as :term:`Source Distribution (sdist)` or :term:`Wheel` +If both are present on PyPI, pip will prefer a compatible :term:`Wheel`. .. note:: - Abhängigkeiten von Wheels werden jedoch nicht erfasst von ``$ pipenv lock``. + However, dependencies on wheels are not covered by ``$ pipenv lock``. Requirement specifier ~~~~~~~~~~~~~~~~~~~~~ -Dabei konkretisieren `Requirement specifier `_ -das jeweilige Paket. +`Requirement specifier `_ specify the +respective package. -* Die aktuelleste Version kann installiert werden, z.B.: +* The latest version can be installed, for example: .. code-block:: console $ pipenv install requests -* Eine spezifische Version kann installiert werden, z.B.: +* A specific version can be installed, for example: .. code-block:: console $ pipenv install requests==2.18.4 -* Soll die Version in einem bestimmten Versionsbereich liegen, kann dies - ebenfalls angegeben werden: +* If the version has to be in a specific version range, this can also be + specified: .. code-block:: console $ pipenv install requests>=2,<3 -* Auch eine kompatible Version lässt sich installieren: +* A compatible version can also be installed: .. code-block:: console $ pipenv install requests~=2.18 - Dies ist kompatibel mit ``==2.18.*``. + This is compatible with ``==2.18.*``. -* Für einige Pakete können auch Installationsoptionen mit `Extras +* For some packages, installation options `Extras `_ - mit eckigen Klammern angegeben werden: + can also be specified with square brackets: .. code-block:: console $ pipenv install requests[security] -* Es kann auch angegeben werden, dass bestimmte Pakete nur auf bestimmten - Systemen installiert werden, so wird bei folgendem ``Pipfile`` das Modul - ``pywinusb`` nur auf Windows-Systemen installiert: +* It can also be specified that certain packages are only installed on certain + systems, so for the following ``Pipfile`` the module ``pywinusb`` is only + installed on Windows systems. .. code-block:: ini [packages] pywinusb = {version = "*", sys_platform = "== 'win32'"} - Ein komplexeres Beispiel unterscheidet, welche Modul-Versionen mit welchen - Python-Versionen installiert werden soll: + A more complex example differentiates which module versions should be + installed with which Python versions: .. code-block:: ini @@ -325,20 +316,19 @@ das jeweilige Paket. VCS ~~~ -Ihr könnt auch Python-Pakete aus Versionsverwaltungen installieren, z.B.: +You can also install Python packages from version control, for example: .. code-block:: console $ pipenv install -e git+https://github.com/requests/requests.git#egg=requests .. note:: - Wenn ``editable=false``, werden Unterabhängigkeiten nicht aufgelöst. + If ``editable=false``, sub-dependencies are not resolved. -Weitere Informationen zu pipenv und VCS erhaltet ihr in `Pipfile spec +Further information on pipenv and VCS can be found in `Pipfile spec `_. -Auch die Credentials der Versionsverwaltung lassen sich im Pipfile angeben, -z.B.: +The version management credentials can also be specified in the pipfile, e.g. .. code-block:: ini @@ -348,61 +338,58 @@ z.B.: name = "cusy-pypi" .. note:: - ``pipenv`` hasht das ``Pipfile``, bevor die Umgebungsvariablen ermittelt - werden, und auch in ``Pipfile.lock`` werden die Umgebungsvariablen - geschrieben, sodass keine Credentials in der Versionsverwaltung gespeichert - werden müssen. + ``pipenv`` hashes ``Pipfile`` before the environment variables are determine, + and the environment variables are also written to ``Pipfile.lock``, so that + no credentials need to be stored in the version control. ``lock`` -------- -``pipenv lock`` generiert die Datei ``Pipfile.lock``, die alle Abhängigkeiten -und Unterabhängigkeiten eures Projekts aufführt inklusive der neuesten -verfügbaren Versionen und der aktuellen Hashwerte für die heruntergeladenen -Dateien. Dies stellt wiederholbare und vor allem deterministische Builds sicher. +``pipenv lock`` generates the file ``Pipfile.lock`` that lists all the +dependencies and sub-dependencies of your project including the latest available +versions and the current hash values for the downloaded files. This ensures +repeatable and, above all, deterministic builds. .. note:: - Um den Determinismus zu erhöhen, kann neben den Hashwerten auch die - Installationsreihenfolge gewährleistet werden. Hierfür gibt es das - ``--sequential``-Flag. + In order to increase the determinism, the installation sequence can also be + guaranteed in addition to the hash values. The ``--sequential`` flag is used + for this. -Security Features +Security features ~~~~~~~~~~~~~~~~~ -``pipfile.lock`` nutzt einige Sicherheitsverbesserungen von ``pip``. So werden -standardmäßig sha256-Hashes jedes heruntergeladenen Pakets generiert. - -Wir empfehlen dringend, ``lock`` zum Deployment von Entwicklungsumgebungen in -die Produktion zu verwenden. Hierbei verwendet ihr ``pipenv lock`` zum -Kompilieren eurer Abhängigkeiten in der Entwicklungsumgebung und anschließend -könnt ihr die kompilierte ``Pipfile.lock``-Datei in der Produktionsumgebung -für reproduzierbare Builds zu verwenden. +``pipfile.lock`` uses some security enhancements from ``pip``: by default, +sha256 hashes are generated for each downloaded package. +We strongly recommend ``lock`` using to deploy development environments to +production. In the development environment you use ``pipenv lock`` to compile +your dependencies and then you can use the compiled file ``Pipfile.lock`` in the +production environment for reproducible builds. ``open`` -------- -``pipenv open MODULE`` zeigt ein bestimmtes Modul in eurem Editor an. +``pipenv open MODULE`` shows a specific module in your editor. -Falls ihr `PyCharm `_ verwendet, müsst ihr -``pipenv`` für euer Python-Projekt konfigurieren. Wie dies geht, ist in +If you use ´PyCharm `_, you have to +configure ``pipenv`` for your Python project. How to do this is described in `Configuring Pipenv Environment -`_ beschrieben. +`_. ``run`` ------- -``pipenv run`` spawnt einen Befehl, der im virtual environment installiert ist, -z.B.: +``pipenv run`` spawns a command that is installed in the virtual environment, +for example: $ pipenv run python main.py ``shell`` --------- -``pipenv shell`` spawnt eine Shell, im virtual environment. Damit erhaltet ihr -einen Python-Interpreter, der alle Python-Pakete enthält und sich somit -hervorragend z.B. zum Debugging und Testen eignet: +``pipenv shell`` spawns a shell in the virtual environment. This gives you a +Python interpreter that contains all Python packages and is therefore ideal for +debugging and testing, for example: .. code-block:: console @@ -414,38 +401,37 @@ hervorragend z.B. zum Debugging und Testen eignet: >>> .. note:: - Shells sind meist nicht so konfiguriert, dass eine Subshell verwendet werden - kann. Dies kann dazu führen, dass ``pipenv shell --fancy`` zu unerwarteten - Ergebnissen führt. In diesen Fällen sollte ``pipenv shell`` verwendet - werden, da diese einen Kompatibilitätsmodus verwendet. + Shells are usually not configured so that a subshell can be used. This can + lead to unexpected results. In these cases ``pipenv shell`` should be used + instead of ``pipenv shell --fancy`` as this uses a compatibility mode. ``sync`` -------- -``pipenv sync`` installiert alle in ``Pipfile.lock`` angegebenen Pakete. +``pipenv sync`` installs all packages specified in ``Pipfile.lock``. ``uninstall`` ------------- -``pipenv uninstall`` deinstalliert alle bereitgestellten Pakete und entfernt sie -aus dem ``Pipfile``. ``uninstall`` unterstützt alle Parameter von `install -<#install>`_ und darüberhinaus die folgenden beiden Optionen: +``pipenv uninstall`` uninstalls all provided packages and removes them from the +``Pipfile``. ``uninstall`` supports all parameters of `install <#install>`_ plus +the following two options: ``--all`` - löscht alle Dateien aus der virtuellen Umgebung, lässt aber ``Pipfile`` - unberührt. + deletes all files from the virtual environment, but leaves the ``Pipfile`` + untouched. ``--all-dev`` - entfernt alle Entwicklungspakete aus der virtuellen Umgebung und entfernt - sie aus ``Pipfile``. + removes all development packages from the virtual environment and removes + them from the ``Pipfile``. ``update`` ---------- -``pipenv update`` führt zunächst ``pipenv lock`` aus, dann ``pipenv sync``. +``pipenv update`` runs first ``pipenv lock``, then ``pipenv sync``. -``pipenv update`` hat u.a. folgende Optionen: +``pipenv update`` has the following options: ``--clear`` - löscht den *Dependency Cache*. + clears the *dependency cache*. ``--outdated`` - listet veraltete Abhängigkeiten auf. + lists obsolete dependencies. diff --git a/docs/productive/envs/pipenv/workflows.rst b/docs/productive/envs/pipenv/workflows.rst index 2c997813..076e23b3 100644 --- a/docs/productive/envs/pipenv/workflows.rst +++ b/docs/productive/envs/pipenv/workflows.rst @@ -1,57 +1,53 @@ Workflows ========= -Im- und Export von ``requirements.txt``-Dateien +Import and export of ``requirements.txt`` files ----------------------------------------------- -Falls ihr in einem bestehenden Projekt bereits eine ``requirements.txt``-Datei -habt, so kann ``pipenv`` diese Abhängigkeiten auflösen. Sofern die -``requirements.txt``-Datei im selben Verzeichnis liegt, einfach mit -``$ pipenv install`` oder falls sie in einem anderen Verzeichnis liegt mit -``$ pipenv install -r /path/to/requirements.txt``. +If you already have a ``requirements.txt`` file in an existing project, +``pipenv`` can resolve dependencies. If the ``requirements.txt`` file is in the +same directory, simply with ``$ pipenv install`` or, if it is in a different +directory, with ``$ pipenv install -r /path/to/requirements.txt``. -Umgekehrt könnt ihr auch aus einer bestehenden Pipenv-Umgebung eine -``requirements.txt``-Datei erzeugen mit: +Conversely, you can also create a ``requirements.txt`` file from an existing +Pipenv environment with: .. code-block:: console $ pipenv run pip freeze > requirements.txt -Upgrade-Workflow +Upgrade workflow ---------------- -#. Findet heraus, was sich *Upstream* geändert hat: +#. Find out what has changed upstream: .. code-block:: console $ pipenv update --outdated Package 'requests' out-of-date: '==2.13.0' installed, '==2.19.1' available. -#. Um die Python-Pakete dann zu aktualisieren, habt ihr die folgenden beiden - Optionen: +#. To update the Python packages, you have the following two options: - * alles aktualisieren mit ``$ pipenv update`` - * einzelne Pakete aktualisieren, z.B. ``requests`` mit ``$ pipenv update requests`` + * update everything with ``$ pipenv update`` + * update individual packages, e.g. ``requests`` with + ``$ pipenv update requests`` ``Pipfile`` vs. ``setup.py`` ---------------------------- -Dabei ist zu unterscheiden, ob ihr eine Anwendung oder eine Bibliothek -entwickelt. - -Bibliotheken - Sie bieten wiederverwendbare Funktionen für andere Bibliotheken und - Anwendungen/Projekte. Sie müssen mit anderen Bibliotheken zusammenarbeiten, - die alle ihre eigenen Abhängigkeiten haben. Um Versionskonflikte in - Abhängigkeiten verschiedener Bibliotheken innerhalb eines Projekts zu - vermeiden, sollten Bibliotheken niemals Abhängigkeitsversionen - festschreiben. Sie können jedoch Unter- oder Obergrenzen angeben, wenn sie - sich auf ein bestimmtes Feature oder einen Bugfix verlassen. - Bibliotheksabhängigkeiten werden über ``install_requires`` in der - ``setup.py`` angegeben. -Anwendungen - Sie verwenden Bibliotheken und sind meist nicht von anderen Projekten - abhängig. Sie sollen in eine bestimmte Umgebung implementiert werden und - erst dann sollten die genauen Versionen aller ihrer Abhängigkeiten und - Subabhängigkeiten konkretisiert werden. Diesen Prozess zu erleichtern, - ist das Hauptziel von Pipenv. +A distinction must be made whether you are developing an application or a +library. + +Libraries + They offer reusable functions for other libraries and applications/projects. + You have to work with other libraries, each with their own dependencies. To + avoid version conflicts in dependencies between different libraries within a + project, libraries should never commit dependency versions. However, you can + specify lower or upper limits if you are relying on a particular feature or + bug fix. Library dependencies are noted in ``install_requires`` of the + ``setup.py`` file. +Applications + They use libraries and are mostly not dependent on other projects. They + should be implemented in a specific environment and only then should the + exact versions of all their dependencies and sub-dependencies be specified. + Facilitating this process is the main goal of Pipenv. diff --git a/docs/productive/envs/spack/build-automatisation.rst b/docs/productive/envs/spack/build-automatisation.rst index e5c02a10..c8f2589b 100644 --- a/docs/productive/envs/spack/build-automatisation.rst +++ b/docs/productive/envs/spack/build-automatisation.rst @@ -1,22 +1,21 @@ -Vorteile der Build-Automatisierung -================================== +Benefits of the build automation +================================ -* Spack erleichtert Teams, ihren Code zu teilen +* Spack makes it easy for teams to share their code - * Rezepte für gebräuchliche Bibliotheken - * reduzieren den Aufwand für reproduzierbare Builds - * und erleichtert damit das Teilen von Builds. + * Recipes for common libraries + * reduce the effort for reproducible builds + * making it easier to share builds. -* Patches erlauben eine schnelle Bereitstellung von Bugfixes +* Patches allow bug fixes to be provided quickly - * Anwendungsentwickler, die eine Bibliothek nutzen, haben häufig keine - Schreibrechte auf deren Repositories. - * Entwickler von Bibliotheken können Probleme evtl. nicht so schnell beheben - wie gewünscht. - * Mit Spack können Anwendungsentwickler schnell Korrekturen vornehmen und - Änderungen rückgängig machen. + * Application developers who use a library often do not have write access to + their repositories. + * Library developers may not be able to fix problems as quickly as desired. + * With Spack, application developers can quickly make corrections and undo + changes. -* Python erlaubt die schnelle Übernahme durch Entwicklungsteams. +* Python allows rapid adoption by development teams. - * Viele Anwendungsentwickler kennen Python bereits. - * Die ``yaml``-Syntax der Specs sind ausdrucksstark. + * Many application developers are already familiar with Python. + * The ``yaml`` syntax of the specs are expressive. diff --git a/docs/productive/envs/spack/combinatorial-builds.rst b/docs/productive/envs/spack/combinatorial-builds.rst index aa923950..8e4c0aac 100644 --- a/docs/productive/envs/spack/combinatorial-builds.rst +++ b/docs/productive/envs/spack/combinatorial-builds.rst @@ -1,5 +1,5 @@ -Kombinatorische Builds -====================== +Combinatorial builds +==================== Environment modules ------------------- @@ -14,17 +14,15 @@ Environment modules $ module load intel/13.0 $ module load mvapich2-pgi-shmem/1.7 -* Vorteile +* Pros - * tauschen verschiedene Versionen dynamisch in der Shell aus - * abstrahieren viel von der Environment-Komplexität + * replace different versions dynamically in the shell + * abstract a lot from the complexity of the environment -* Nachteile +* Cons - * Benutzer müssen daran denken, mit welchen Versionen der Build - durchgeführt wurde - * Es ist einfach, das falsche Modul zu laden und einen Build fehlschlagen - zu lassen + * Users need to keep in mind which versions of the build were made + * It’s easy to load the wrong module and cause a build to fail Dependency DAG -------------- @@ -60,7 +58,7 @@ Dependency DAG libdwarf -> libelf } -Installationslayout +Installation layout ------------------- .. code-block:: console @@ -75,19 +73,18 @@ Installationslayout │   │   │   ├── autoheader ... -* Jeder eindeutige Abhängigkeitsgraph erhält eine einzigartige Konfiguration -* Jede Konfiguration ist in einem eindeutigen Verzeichnis installiert +* Each unique dependency graph is given a unique configuration +* Each configuration is installed in a unique directory - * Konfigurationen des gleichen Pakets koexistieren nebeneinander + * Configurations of the same package coexist -* Der Hash-Wert eines gerichteten azyklischen Graphen wird angehängt -* Installierte Pakete finden automatisch ihre Abhängigkeiten +* The hash value of a directed acyclic graph is appended +* Installed packages automatically find their dependencies - * Spack bettet ``RPATH`` in Binärdateien ein - * Es besteht keine Notwendigkeit, Module zu verwenden oder - ``LD_LIBRARY_PATH`` zu setzen + * Spack embeds ``RPATH`` in binary files + * There is no need to use modules or to set the ``LD_LIBRARY_PATH`` -``spack list`` zeigt die verfügbaren Pakete: +``spack list`` shows the available packages: .. code-block:: console @@ -98,70 +95,69 @@ Installationslayout accfft py-flake8 ... -Spack bietet eine ``spec``-Syntax zum Beschreiben benutzerdefinierter DAGs: +Spack provides a ``spec`` syntax for describing custom DAGs: -* ohne Einschränkungen +* without restrictions .. code-block:: console $ spack install mpileaks -* ``@``: Benutzerdefinierte Version +* ``@``: custom version .. code-block:: console $ spack install mpileaks@3.3 -* ``%``: Benutzerdefinierter Compiler +* ``%``: custom compiler .. code-block:: console $ spack install mpileaks@3.3 %gcc@4.7.3 -* ``+``/``-``: Build-Option +* ``+``/``-``: Build option .. code-block:: console $ spack install mpileaks@3.3 %gcc@4.7.3 +threads -* ``=``: Cross-compile +* ``=``: Cross compile .. code-block:: console $ spack install mpileaks@3.3 =bgq -* ``^``: Version von Abhängigkeiten +* ``^``: Version of dependencies .. code-block:: console $ spack install mpileaks %intel@12.1 ^libelf@0.8.12 -* Spack stellt eine Konfiguration jeder Bibliothek pro DAG sicher +* Spack ensures a configuration of each library per DAG - * gewährleistet die Konsistenz des Application Binary Interface (ABI) - * Der Benutzer muss die DAG-Struktur nicht kennen, sondern nur die Namen der - abhängigen Bibliotheken + * ensures the consistency of the Application Binary Interface (ABI) + * The user does not need to know the DAG structure, just the names of the + dependent libraries -* Spack kann sicherstellen, dass Builds den gleichen Compiler verwenden -* Es können auch verschiedene Compiler für verschiedene Bibliotheken eines DAG - angegeben werden -* Spack kann auch ABI-inkompatible, versionierte Schnittstellen wie z.B. das - Message Passing Interface (MPI) bereitstellen -* So kann z.B. ``mpi`` auf unterschiedliche Weise erstellt werden: +* Spack can ensure that builds use the same compiler +* Different compilers can also be specified for different libraries of a DAG +* Spack can also provide ABI-incompatible, versioned interfaces such as the + Message Passing Interface (MPI) +* For example, you can create ``mpi`` in different ways: .. code-block:: console $ spack install mpileaks ^mvapich@1.9 $ spack install mpileaks ^openmpi@1.4 -* Alternativ kann Spack auch selbst das passende Build wählen sofern nur das - MPI 2-Interface implementiert wird: +* Alternatively, Spack can also choose the right build himself if only the MPI + 2 interface is implemented: .. code-block:: console $ spack install mpileaks ^mpi@2 -* Spack-Pakete sind einfache Python-Skripte: +* Spack packages are simple Python scripts: .. code-block:: python @@ -198,9 +194,9 @@ Spack bietet eine ``spec``-Syntax zum Beschreiben benutzerdefinierter DAGs: make() make("install") -* Abhängigkeiten in Spack können optional sein: +* Dependencies in Spack can be optional: - * Ihr könnt *named variants* definieren, wie z.B. in + * You can define *named variants*, e.g. in ``~/spack/var/spack/repos/builtin/packages/vim/package.py``: .. code-block:: python @@ -213,34 +209,32 @@ Spack bietet eine ``spec``-Syntax zum Beschreiben benutzerdefinierter DAGs: variant('ruby', default=False, description="build with Ruby") depends_on('ruby', when='+ruby') - * … und zum Installieren verwenden: + * … and use to install: .. code-block:: console $ spack install vim +python $ spack install vim –python - * Abhängig von anderen Bedingungen können Abhängigkeiten optional gelten, - z.B. gcc-Abhängigkeit von mpc ab Version 4.5: + * Depending on other conditions, dependencies can optionally apply, e.g. gcc + dependency on mpc from version 4.5: .. code-block:: python depends_on("mpc", when="@4.5:") -* DAGs sind nicht immer vollständig bevor sie konkretisiert werden. - Konkretisierungen füllen die fehlenden Konfigurationsdetails aus wenn ihr sie - nicht explizit benennt: +* DAGs are not always complete before they are specified. Concretisations fill + in the missing configuration details if you do not name them explicitly: - #. Normalisierung + #. Normalisation .. code-block:: console $ spack install mpileaks ^callpath@1.0+debug ^libelf@0.8.11 - #. Konkretisierung + #. Specification - Die detaillierte Herkunft wird mit dem installierten Paket in - ``spec.yaml`` gespeichert: + The detailed origin is saved with the installed package in ``spec.yaml``: .. code-block:: yaml @@ -279,10 +273,10 @@ Spack bietet eine ``spec``-Syntax zum Beschreiben benutzerdefinierter DAGs: version: 1.59.0 ... - #. Wenn unspezifiziert, werden bei der Konkretisierung Werte basierend auf - den Nutzereinstellungen gewählt. - #. Bei der Konkretisierung werden neue Abhängigkeiten unter - Berücksichtigung der Constraints hinzugefügt. - #. Beim aktuellen Algorithmus kann nicht zurückverfolgt werden, warum eine - Entscheidung getroffen wurde. - #. Zukünftig soll es einen *Full constraint solver* geben. + #. If unspecified, values based on the user settings are selected during + the specification. + #. During the concretisation, new dependencies are added taking the + constraints into account. + #. With the current algorithm, it is not possible to trace why a decision + was made. + #. In the future there should be a full constraint solver. diff --git a/docs/productive/envs/spack/envs.rst b/docs/productive/envs/spack/envs.rst index 92c3260f..95233920 100644 --- a/docs/productive/envs/spack/envs.rst +++ b/docs/productive/envs/spack/envs.rst @@ -1,7 +1,7 @@ -Environments, ``spack.yaml`` und ``spack.lock`` +Environments, ``spack.yaml`` and ``spack.lock`` =============================================== -#. Erstellen einer virtuellen Umgebung: +#. Create a virtual environment: .. code-block:: console @@ -9,8 +9,7 @@ Environments, ``spack.yaml`` und ``spack.lock`` ==> Updating view at /Users/veit/spack/var/spack/environments/python-374/.spack-env/view ==> Created environment 'python-374' in /Users/veit/spack/var/spack/environments/python-374 - Alternativ kann sie auch an beliebigen anderen Orten gespeichert werden, - z.B.: + Alternatively, it can also be saved in any other location, for example:, .. code-block:: console @@ -19,7 +18,7 @@ Environments, ``spack.yaml`` und ``spack.lock`` ==> Updating view at /srv/jupyter/jupyter-tutorial/spackenvs/python-374/.spack-env/view ==> Created environment in /srv/jupyter/jupyter-tutorial/spackenvs/python-374 -#. Überprüfen der virtuellen Umgebung: +#. Check the virtual environment: .. code-block:: console @@ -27,17 +26,16 @@ Environments, ``spack.yaml`` und ``spack.lock`` ==> 1 environments python-374 -#. Aktivieren der virtuellen Umgebung: +#. Activate the virtual environment: .. code-block:: console $ spack env activate python-374 -#. Überprüfen der Aktivierung: +#. Check activation: - Wenn ihr eine Umgebung aktiviern habt, wird euch nur das angezeigt, was sich - in der aktuellen Umgebung befindet. Das sollte unmittelbar nach der - Aktivierung nichts sein: + If you have activated an environment, you will only see what is in the + current environment. That shouldn’t be anything immediately after activation: .. code-block:: console @@ -47,16 +45,16 @@ Environments, ``spack.yaml`` und ``spack.lock`` ==> 0 installed packages - Und wenn ihr überprüfen möchtet, in welcher Umgebung ihr euch befindet, dann - könnt ihr dies abfragen mit: + And if you want to check what environment you are in, you can query this + with: .. code-block:: console $ spack env status ==> In environment python-374 -#. Schließlich könnt ihr die aktivierte Umgebung verlassen mit ``spack env - deactivate`` oder kurz ``despacktivate``. +#. Finally, you can leave the activated environment with ``spack env + deactivate`` or briefly ``despacktivate``. .. code-block:: console @@ -71,8 +69,8 @@ Environments, ``spack.yaml`` und ``spack.lock`` expat@2.2.5 openblas@0.3.6 py-numpy@1.16.4 sqlite@3.28.0 gdbm@1.18.1 openssl@1.1.1b py-setuptools@41.0.1 xz@5.2.4 -Compiler installieren ---------------------- +Install compiler +---------------- #. Installation @@ -82,10 +80,10 @@ Compiler installieren … [+] /srv/jupyter/spack/opt/spack/linux-ubuntu18.04-sandybridge/gcc-7.4.0/gcc-9.1.0-zaj3xkm5onfgeweaeav5kuubwmjaokmz -#. Konfiguration +#. Configuration - Um den neuen gcc-Compiler verwenden zu können, muss er in - ``~/.spack/linux/compilers.yaml`` eingetragen werden mit: + In order to be able to use the new gcc compiler, it must be entered in + ``~/.spack/linux/compilers.yaml``: .. code-block:: console @@ -95,7 +93,7 @@ Compiler installieren ==> Compilers are defined in the following files: /srv/jupyter/.spack/linux/compilers.yaml -#. Überprüfen +#. Check .. code-block:: console @@ -105,8 +103,8 @@ Compiler installieren autoconf@2.69 gcc@9.1.0 gmp@6.1.2 libsigsegv@2.12 m4@1.4.18 mpfr@3.1.6 perl@5.30.1 readline@8.0 automake@1.16.1 gdbm@1.18.1 isl@0.20 libtool@2.4.6 mpc@1.1.0 ncurses@6.1 pkgconf@1.6.3 zlib@1.2.11 -Pakete installieren -------------------- +Install packages +---------------- .. code-block:: console @@ -121,7 +119,7 @@ Pakete installieren -- linux-debian9-x86_64 / gcc@9.1.0 ----------------------------- bzip2@1.0.6 expat@2.2.5 gdbm@1.18.1 libbsd@0.9.1 libffi@3.2.1 ncurses@6.1 openblas@0.3.5 openssl@1.1.1b py-numpy@1.16.2 python@3.7.2 readline@7.0 sqlite@3.26.0 xz@5.2.4 zlib@1.2.11 -Mit ``spack cd -e python-374`` könnt ihr in dieses Verzeichnis wechseln, z.B.: +With ``spack cd -e python-374`` you can change to this directory, for example: .. code-block:: console @@ -129,21 +127,20 @@ Mit ``spack cd -e python-374`` könnt ihr in dieses Verzeichnis wechseln, z.B.: $ pwd /Users/veit/spack/var/spack/environments/python-374 -Dort befinden sich die beiden Dateien ``spack.yaml`` und ``spack.lock``. +There you will find the two files ``spack.yaml`` and ``spack.lock``. ``spack.yaml`` - ist die Konfigurationsdatei für die virtuelle Umgebung. Sie wird in - ``~/spack/var/spack/environments/`` beim Aufruf von ``spack env create`` - erstellt. + is the configuration file for the virtual environment. It is created in + ``~/spack/var/spack/environments/`` when you call ``spack env create``. - Alternativ zu ``spack install`` können in ``spack.yaml`` auch der - ``specs``-Liste Python-3.7.4, Numpy etc. hinzugefügt werden: + As an alternative to ``spack install`` Python-3.7.4, Numpy etc. can also be + added to the ``specs`` list in ``spack.yaml``: .. code-block:: yaml specs: [gcc@9.1.0, python@3.7.4%gcc@9.1.0, py-numpy ^python@3.7.4, …] - Schließlich kann die virtuelle Umgebung erstellt werden mit: + Finally, the virtual environment can be created with: .. code-block:: console @@ -161,9 +158,10 @@ Dort befinden sich die beiden Dateien ``spack.yaml`` und ``spack.lock``. … ``spack.lock`` - Mit ``spack install`` werden die Specs konkretisiert, in ``spack.lock`` geschrieben und installiert. - Im Gegensatz zu ``spack.yaml`` ist ``spack.lock`` im ``json``-Format geschrieben und enthält die - notwendigen Informationen um reproduzierbare Builds der Umgebung erstellen zu können: + With ``spack install`` the specs are concretized, written in ``spack.lock`` + and installed. In contrast to ``spack.yaml`` ``spack.lock`` is written in + ``json`` format and contains the necessary information to be able to create + reproducible builds of the environment: .. code-block:: javascript @@ -219,12 +217,12 @@ Dort befinden sich die beiden Dateien ``spack.yaml`` und ``spack.lock``. } } -Installation zusätzlicher Pakete --------------------------------- +Installation of additional packages +----------------------------------- -Zusätzliche Pakete können in der virtuellen Umgebung installiert werden mit -``spack add`` und ``spack install``. Für `Matplotlib `_ -sieht dies z.B. folgendermaßen aus: +Additional packages can be installed in the virtual environment with ``spack +add`` and ``spack install``. For `Matplotlib `_ it +looks like this: .. code-block:: console @@ -241,9 +239,9 @@ sieht dies z.B. folgendermaßen aus: [+] /srv/jupyter/spack/opt/spack/linux-debian9-x86_64/gcc-9.1.0/py-matplotlib-3.0.2-4d6nj4hfo3yvkqovp243p4qeebeb5zl6 .. note:: - Falls von diesem Spack-Environment bereits ein :doc:`Pipenv-Environment - <../pipenv/env>` abgeleitet wurde, muss dieses neu gebaut werden um das - zusätzliche Spack-Paket zu erhalten: + If a :doc:`Pipenv environment <../pipenv/env>` has already been derived from + this Spack environment, it must be rebuilt in order to receive the additional + Spack package: .. code-block:: console @@ -266,7 +264,7 @@ sieht dies z.B. folgendermaßen aus: To activate this project's virtualenv, run pipenv shell. Alternatively, run a command inside the virtualenv with pipenv run. - Anschließend kann die Installation überprüft werden mit: + The installation can then be checked with: .. code-block:: console @@ -276,10 +274,10 @@ sieht dies z.B. folgendermaßen aus: Type "help", "copyright", "credits" or "license" for more information. >>> import matplotlib.pyplot as plt -Konfiguration +Configuration ------------- -``spack spec`` spezifiziert die Abhängigkeiten bestimmter Pakete, z.B.: +``spack spec`` specifies the dependencies of certain packages, e.g. .. code-block:: console @@ -298,8 +296,8 @@ Konfiguration ^libpng@1.6.34%gcc@9.1.0 arch=linux-debian9-x86_64 ^zlib@1.2.11%gcc@9.1.0+optimize+pic+shared arch=linux-debian9-x86_64 -Mit ``spack config get`` könnt ihr euch die Konfiguration einer bestimmten -Umgebung anschauen: +With ``spack config get`` you can look at the configuration of a certain +environment: .. code-block:: console @@ -320,24 +318,25 @@ Umgebung anschauen: config: {} upstreams: {} -Mit ``spack config edit`` kann die Konfigurationsdatei ``spack.yaml`` editiert werden. +With ``spack config edit`` the configuration file ``spack.yaml`` can be edited. .. note:: - Wenn in der Umgebung bereits Pakete installiert sind, sollten mit ``spack - concretize -f`` alle Abhängigkeiten erneut spezifiziert werden. + If packages are already installed in the environment, all dependencies + should be specified again with ``spack concretize -f``. -Laden der Module ----------------- -Mit ``spack env loads -r `` werden alle Module mit ihren Abhängigkeiten -geladen. +Loading the modules +------------------- + +With ``spack env loads -r `` all modules are loaded with their +dependencies. .. note:: - Aktuell funktioniert dies jedoch nicht beim Laden der Module aus - Environments, die nicht in ``$SPACK_ROOT/var/environments`` liegen. + However, this does not currently work when loading modules from environments + that are not in ``$SPACK_ROOT/var/environments``. - Daher ersetzen wir das Verzeichnis ``$SPACK_ROOT/var/environments`` durch - einen symbolischen Link: + Therefore we replace the directory ``$SPACK_ROOT/var/environments`` with a + symbolic link: .. code-block:: console diff --git a/docs/productive/envs/spack/future.rst b/docs/productive/envs/spack/future.rst index ef957d32..fea8e3dd 100644 --- a/docs/productive/envs/spack/future.rst +++ b/docs/productive/envs/spack/future.rst @@ -1,10 +1,10 @@ -Zukünftige Features -=================== +Future features +=============== -* Lmod (Lua based module system)-Integration -* Auflösen externer Abhängigkeiten -* Benutzerdefinierte Compiler Flag Injection -* XML-Testergebnisse (JUnit) +* Lmod (Lua based module system) integration +* Resolve external dependencies +* Custom compiler flag injection +* XML test results (JUnit) .. seealso:: `Pull requests `_ diff --git a/docs/productive/envs/spack/index.rst b/docs/productive/envs/spack/index.rst index 446863f3..e23cf034 100644 --- a/docs/productive/envs/spack/index.rst +++ b/docs/productive/envs/spack/index.rst @@ -1,38 +1,37 @@ Spack ===== -Modellierungs- und Simulationsumgebungen sind sehr heterogen. :doc:`Spack -` unterstützt daher viele verschiedene Produktionsumgebungen: +Modeling and simulation environments are very heterogeneous. :doc:`Spack +` therefore supports many different production environments: -* 7 verschiedene Compiler: Intel, GCC, Clang, PGI, … -* Auflösen von Abhängigkeiten -* Auflösen verschiedener Versionen von Abhängigkeiten +* 7 different compilers: Intel, GCC, Clang, PGI, … +* Resolving dependencies +* Resolving different versions of dependencies -Bisherige Systeme ------------------ +Previous systems +---------------- -Sie bieten meist keine Unterstützung für kombinatorische Versionierung. +They usually do not offer any support for combinatorial versioning. -* Traditionelle Binärpaketmanager wie RPM, yum, APT, yast, etc. +* Traditional binary package managers like RPM, yum, APT, yast, etc. - * sind konzipiert um einen einzelnen Software-Stack zu verwalten - * installieren eine Version eines Pakets - * üblicherweise problemlose Upgrades auf einen stabilen, gut getesteten - Stack + * are designed to manage a single software stack + * install one version of a package + * usually problem-free upgrades to a stable, well-tested stack -* Port-Systeme +* Port systems * BSD Ports, portage, NixOS, Macports, Homebrew, etc. - * meist kaum Unterstützung für Builds, die parametrisiert sind durch - Compiler oder abhängige Versionen + * mostly little support for builds that are parameterised by compilers or + dependent versions -* Virtuelle Maschinen und Linux-Container +* Virtual machines and Linux containers - * Container erlauben die Erstellung unterschiedlicher Umgebungen für - unterschiedliche Anwendungen - * Sie lösen jedoch nicht das Build-Problem für das Image - * Performance, Security und Upgrades werden bei vielen unterschiedlichen - Builds sehr aufwändig. + * Containers allow the creation of different environments for different + applications + * However, they do not solve the build problem for the image + * Performance, security and upgrades become very complex with many different + builds. .. toctree:: :hidden: diff --git a/docs/productive/envs/spack/install.rst b/docs/productive/envs/spack/install.rst index 13e1775a..2afede4f 100644 --- a/docs/productive/envs/spack/install.rst +++ b/docs/productive/envs/spack/install.rst @@ -1,33 +1,33 @@ -Spack-Installation +Spack installation ================== -Anforderungen -------------- +Requirements +------------ -* Python 2 oder Python 3 +* Python 2 or Python 3 * C/C++ compiler -* ``git`` und ``curl`` +* ``git`` and ``curl`` - Für Linux: + For Linux: .. code-block:: console $ apt install curl git environment-modules - … oder für macOS: + … or for macOS: .. code-block:: console $ brew install curl git modules - Anschließend wird die Shell konfiguriert indem z.B. für die Bash folgendes in - die Bash-Konfiguration eingetragen wird: + Then the shell is configured by entering for example the following in the Bash + configuration: .. code-block:: console $ source /usr/local/opt/modules/init/bash -* ``gnupg2`` für ``gpg``-Subcommand +* ``gnupg2`` for the ``gpg`` subcommand Installation ------------ @@ -38,25 +38,25 @@ Installation Cloning into 'spack'... ... -Shell konfigurieren +Configure the shell ------------------- -#. Zur Konfiguration des Bash-Environment wird folgendes in ``~/.bashrc`` - eingetragen: +#. To configure the bash environment, the following is entered in the + ``~/.bashrc``: .. code-block:: bash export SPACK_ROOT=~/spack . $SPACK_ROOT/share/spack/setup-env.sh -#. Die geänderte Konfiguration wird nun übernommen mit +#. The changed configuration is read with .. code-block:: console $ source ~/.bashrc -Überprüfen der Installation ---------------------------- +Checking the installation +------------------------- .. code-block:: console @@ -87,7 +87,7 @@ Shell konfigurieren ^perl@5.30.1%gcc@7.4.0+cpanm+shared+threads arch=linux-ubuntu18.04-sandybridge ^sqlite@3.30.1%gcc@7.4.0~column_metadata+fts~functions~rtree arch=linux-ubuntu18.04-sandybridge -Compiler-Konfiguration +Compiler configuration ---------------------- .. code-block:: console @@ -97,53 +97,50 @@ Compiler-Konfiguration -- clang mojave-x86_64 ------------------------------------------ clang@10.0.1-apple -GPG Signing +GPG signing ----------- -Spack unterstützt das Signieren und Verifizieren von Paketen mit -GPG-Schlüsseln. Für Spack wird ein separater Schlüsselring verwendet, weswegen -keine Schlüssel aus dem Home-Verzeichnis von Nutzern verfügbar sind. +Spack supports the signing and verification of packages with GPG keys. A +separate key ring is used for Spack, why no keys are available from users’ home +directories. -Wenn Spack zum ersten Mal installiert wird, ist dieser Schlüsselring leer. -Die in ``/var/spack/gpg`` gespeicherten Schlüssel sind die Standardschlüssel -für eine Spack-Installation. Diese Schlüssel werden durch ``spack gpg init`` -importiert. Dadurch werden die Standardschlüssel als vertrauenswürdige Schlüssel -in den Schlüsselbund importiert. +When Spack is first installed, this key ring will be empty. The keys stored in +``/var/spack/gpg`` are the standard keys for a Spack installation. These keys +are imported by ``spack gpg init``. This will import the standard keys into the +keyring as trusted keys. -Schlüsseln vertrauen -~~~~~~~~~~~~~~~~~~~~ +Trust keys +~~~~~~~~~~ -Zusätzliche Schlüssel können dem Schlüsselring hinzugefügt werden mit -``spack gpg trust ``. Sobald ein Schlüssel vertrauenswürdig ist, -können Pakete, die vom Besitzer dieses Schlüssels signiert wurden, installiert -werden. +Additional keys can be added to the key ring using ``spack gpg trust +``. Once a key is trusted, packages signed by the owner of that key can +be installed. -Schlüssel erstellen -~~~~~~~~~~~~~~~~~~~ +Create a key +~~~~~~~~~~~~ -Ihr könnt auch eigene Schlüssel erstellen um eure eigenen Pakete signieren -zu können mit +You can also create your own keys to be able to sign your own packages with .. code-block:: console $ spack gpg export […] -Schlüssel auflisten -~~~~~~~~~~~~~~~~~~~ +List keys +~~~~~~~~~ -Die im Schlüsselbund verfügbaren Schlüssel können aufgelistet werden mit +The keys available in the keyring can be listed with .. code-block:: console $ spack gpg list -Schlüssel entfernen -~~~~~~~~~~~~~~~~~~~ +Remove a key +~~~~~~~~~~~~ -Schlüssel können entfernt werden mit +Keys can be removed with .. code-block:: console $ spack gpg untrust -Schlüssel-IDs können E-Mail-Adressen, Namen oder Fingerprints sein. +Key IDs can be email addresses, names or fingerprints. diff --git a/docs/productive/envs/spack/mirrors.rst b/docs/productive/envs/spack/mirrors.rst index 8faaa0d7..9e6cbb9e 100644 --- a/docs/productive/envs/spack/mirrors.rst +++ b/docs/productive/envs/spack/mirrors.rst @@ -1,13 +1,12 @@ -Spack Mirrors +Spack mirrors ============= -Einige Maschinen haben möglicherweise keinen Internetzugang, um Pakete -abzurufen. Sie benötigen dann ein lokales Repository mit Tarballs, aus denen sie -ihre Dateien abrufen können. Spack unterstützt dies mit :doc:`mirrors`. Ein -Mirror ist eine URL, die auf ein Verzeichnis im lokalen Dateisystem oder auf -einem Server verweist und Tarballs für alle Pakete von Spack enthält. +Some machines may not have internet access to get packages. Then you will need a +local repository of tarballs from which to retrieve your files. Spack supports +this with :doc:`mirrors`. A mirror is a URL that points to a directory on the +local file system or on a server and contains tarballs for all Spack packages. -Hier ist ein Beispiel für die Verzeichnisstruktur eines Mirror: +Here is an example of the directory structure of a mirror: .. code-block:: console @@ -30,26 +29,25 @@ Hier ist ein Beispiel für die Verzeichnisstruktur eines Mirror: ``spack mirror create`` ----------------------- -Ihr könnt mit dem Befehl ``spack mirror create`` einen Mirror erstellen, -vorausgesetzt, ihr befindet euch auf einer Maschine, die auf das Internet -zugreifen kann. Der Befehl durchläuft alle Pakete von Spack und lädt die -gewünschten herunter. +You can create a mirror with the command ``spack mirror create``, provided you +are on a machine that can access the Internet. The command iterates through all +of Spack’s packages and downloads the ones you want. ``spack mirror add`` -------------------- -Sobald ihr einen Spiegel erstellt habt, müsst ihr Spack darüber informieren. Das -ist relativ einfach. Ermittelt zunächst die URL eures Mirrors. Wenn es sich um -ein Verzeichnis handelt, könnt ihr eine Datei-URL wie die folgende verwenden: +Once you’ve created a mirror, you need to let Spack know about it. It’s +relatively easy. First find out the URL of your mirror. If it’s a directory, you +can use a file url like this: .. code-block:: console $ spack mirror add local_filesystem file://$HOME/spack-mirror -Reihenfolge der Mirrors ------------------------ +Order of mirrors +---------------- -``spack mirror ad`` fügt eine Zeile hinzu in ``~/.spack/mirrors.yaml``: +``spack mirror ad`` adds a line in ``~/.spack/mirrors.yaml``: .. code-block:: yaml @@ -57,15 +55,14 @@ Reihenfolge der Mirrors local_filesystem: file:///home/veit/spack-mirror remote_server: https://spack-mirror.cusy.io -Wenn ihr die Reihenfolge ändern möchtet, in der Mirrors nach Paketen durchsucht -werden, könnt ihr diese Datei bearbeiten und die Abschnitte neu anordnen: Spack -durchsucht diese von oben nach unten bis ein passender Eintrag gefunden wird. +If you want to change the order in which mirrors are searched for packages, you +can edit this file and rearrange the sections: Spack searches them from top to +bottom until a suitable entry is found. -Lokaler Standardcache ---------------------- +Local default cache +------------------- -Spack erstellt einen Zwischenspeicher für Ressourcen, die im Rahmen von -Installationen heruntergeladen werden. Dieser Cache ist ein gültiger -Spack-Mirror: er verwendet dieselbe Verzeichnisstruktur und dasselbe -Namensschema wie andere Spack-Mirror. Der Mirror wird lokal im -Spack-Installationsverzeichnis verwaltet unter ``~/spack/var/spack/cache/``. +Spack creates a cache for resources that are downloaded as part of +installations. This cache is a valid Spack mirror: it uses the same directory +structure and naming scheme as other Spack mirrors. The mirror is managed +locally in the Spack installation directory at ``~/spack/var/spack/cache/``. diff --git a/docs/productive/envs/spack/use.rst b/docs/productive/envs/spack/use.rst index 2993ea68..d0a7072f 100644 --- a/docs/productive/envs/spack/use.rst +++ b/docs/productive/envs/spack/use.rst @@ -1,8 +1,8 @@ -Spack verwenden -=============== +Use spack +========= -Auflisten der verfügbaren Pakete --------------------------------- +List the available packages +--------------------------- .. code-block:: console @@ -12,7 +12,7 @@ Auflisten der verfügbaren Pakete abyss py-fiscalyear … -oder zum filtern nach bestimmten Paketen, z.B. +or to filter for certain packages, e.g. .. code-block:: console @@ -20,8 +20,8 @@ oder zum filtern nach bestimmten Paketen, z.B. ==> 2 packages. py-numpy py-numpydoc -Auflisten der installierten Pakete ----------------------------------- +List the installed packages +--------------------------- .. code-block:: console @@ -113,7 +113,7 @@ Auflisten der installierten Pakete ``spack version`` ----------------- -``spack version`` zeigt die verfügbaren Versionen an, z.B. +``spack version`` shows the available versions, e.g. .. code-block:: console @@ -128,22 +128,22 @@ Auflisten der installierten Pakete 3.8.0b1 3.6.8rc1 3.5.6rc1 3.5.0a1 3.3.7rc1 3.1.1 2.6.9 2.4.2 … -Installation bestimmter Pakete ------------------------------- +Installation of certain packages +-------------------------------- -z.B.: +e.g.: .. code-block:: console $ spack install python@3.7.4 -oder um ``py-numpy`` für Python 3.7.4 zu installieren: +or to install ``py-numpy`` for Python 3.7.4: .. code-block:: console $ spack install py-numpy ^python@3.7.4 -Anschließend kann die Installation überprüft werden mit +Then the installation can be checked with .. code-block:: console @@ -164,31 +164,30 @@ Anschließend kann die Installation überprüft werden mit ^sqlite@3.28.0 ^xz@5.2.4 -Deinstallieren -~~~~~~~~~~~~~~ +Uninstall +~~~~~~~~~ .. code-block:: console $ spack uninstall py-numpy -oder +or .. code-block:: console $ spack uninstall --dependents py-numpy -Extensions und Python-Support +Extensions and Python support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Das Installationsmodell von Spack geht davon aus, dass jedes Paket in einem -eigenen Installations-Präfix lebt. Module in interpretierten Sprachen wie -Python werden typischerweise im ``$prefix/lib/python-3.7/site-packages/`` -installiert, also z.B. +The Spack installation model assumes that each package lives in its own +installation prefix. Modules in interpreted languages such as Python are +typically installed in ``$prefix/lib/python-3.7/site-packages/``, e.g. ``/Users/veit/spack/opt/spack/darwin-mojave-x86_64/clang-10.0.1-apple/py-numpy-1.16.4-45sqnufha2yprpx6rxyelsokky65ucdy/lib/python3.7/site-packages/numpy``. -Es können jedoch auch Pakete verwendet werden, die in einem anderen Präfix -installiert wurden. In Spack wird ein solches Paket als *Extension* bezeichnet. +However, packages installed in a different prefix can also be used. Such a +package is called an *extension* in Spack. -Angenommen, Python wurde installiert mit +Suppose Python was installed with .. code-block:: console @@ -197,7 +196,7 @@ Angenommen, Python wurde installiert mit -- darwin-mojave-x86_64 / clang@10.0.1-apple -------------------- python@3.7.4 -so können *Extensions* gefunden werden mit +so *Extensions* can be found with .. code-block:: console @@ -214,8 +213,7 @@ so können *Extensions* gefunden werden mit ==> None activated. -``numpy`` kann dem ``PYTHONPATH`` der aktuellen Shell hinzugefügt werden mit -``load``: +``numpy`` can be added to the ``PYTHONPATH`` of the current shell with ``load``: .. code-block:: console @@ -228,8 +226,8 @@ so können *Extensions* gefunden werden mit >>> import numpy >>> -Oft sollen jedoch bestimmte Pakete dauerhaft einer Python-Installation zur -Verfügung stehen. Spack bietet hierfür ``activate`` an: +Often, however, certain packages should be permanently available to a Python +installation. Spack offers ``activate`` for this: .. code-block:: console diff --git a/docs/productive/envs/spack/usecase1.rst b/docs/productive/envs/spack/usecase1.rst index a8a4bf5d..27162921 100644 --- a/docs/productive/envs/spack/usecase1.rst +++ b/docs/productive/envs/spack/usecase1.rst @@ -1,8 +1,8 @@ -Use Case 1: Verwalten kombinatorischer Installationen -===================================================== +Use case 1: managing combinatorial installations +================================================ -Anzeige aller installierten Konfigurationen -------------------------------------------- +Display all installed configurations +------------------------------------ .. code-block:: console @@ -21,14 +21,13 @@ Anzeige aller installierten Konfigurationen boost@1.55.0 hwloc@1.9 libelf@0.8.13 starpu@1.1.4 -* ``spack find`` zeigt alle installierten Konfigurationen -* Dabei kann es auch verschiedene Versionen desselben Pakets geben -* Pakete werden differenziert zwischen Architektur und Compiler -* Spack generiert ebenfalls ``modulefiles``, diese müssen jedoch nicht genutzt - werden +* ``spack find`` shows all installed configurations +* There can also be different versions of the same package +* Packages are differentiated between architecture and compiler +* Spack also generates ``modulefiles``, but these do not have to be used -Spack-Syntax zum Einschränken der Anfragen ------------------------------------------- +Spack syntax to restrict the requests +------------------------------------- .. code-block:: console @@ -55,7 +54,7 @@ Spack-Syntax zum Einschränken der Anfragen -- linux-x86_64 / intel@15.0.1 ------ libelf@0.8.13 -Spack-Syntax zum Anzeigen der Abhängigkeiten +Spack syntax for displaying the dependencies -------------------------------------------- .. code-block:: console diff --git a/docs/productive/envs/spack/usecase2.rst b/docs/productive/envs/spack/usecase2.rst index cd02ba45..527d8442 100644 --- a/docs/productive/envs/spack/usecase2.rst +++ b/docs/productive/envs/spack/usecase2.rst @@ -1,5 +1,5 @@ -Use Case 2: Python und andere interpretierte Sprachen -===================================================== +Use case 2: Python and other interpreted languages +================================================== .. code-block:: console diff --git a/docs/productive/git/best-practices.rst b/docs/productive/git/best-practices.rst index 361ec25f..b0f76dbf 100644 --- a/docs/productive/git/best-practices.rst +++ b/docs/productive/git/best-practices.rst @@ -1,11 +1,11 @@ -Git Best Practices +Git best practices ================== -- Macht früh Commits! +- Commit early! - Macht Euren ersten Commit nachdem ihr die initiale Installation - fertiggestellt habt und noch bevor ihr erste Änderungen vornehmt. Für ein - Cookiecutter-Template z.B. nach den folgenden Schritten: + Make your first commit after you’ve finished the initial installation and + before you make your first changes. For a cookiecutter template, for example, + following the following steps: .. code-block:: console @@ -16,23 +16,22 @@ Git Best Practices project_name [cusy.example]: … - Falls in eurem Projekt noch keine ``.gitignore``-Datei vorhanden ist, solltet - ihr diese anlegen und zumindest ``.ipynb_checkpoints`` und - ``*/.ipynb_checkpoints/*`` ausschließen:: + If no ``.gitignore`` file is present in your project, you should create one + and at least -exclude ``.ipynb_checkpoints`` and ``*/.ipynb_checkpoints/*``. - Falls ihr versehentlich schon entsprechende Dateien in euer Git-Repository - eingecheckt habt, könnt ihr diese wieder entfernen mit: + + If you have accidentally checked the corresponding files into your Git + repository, you can remove them again with: .. code-block:: console $ git rm -r .ipynb_checkpoints/ - Eine Übersicht über weitere ``.gitignore``-Einträge - erhaltet ihr entweder im Repository `dotfiles - `_ oder auf der Website `gitignore.io - `_. + You can get an overview of other ``.gitignore`` entries either in the + `dotfiles `_ repository or on the + `gitignore.io `_ website. - Anschließend können diese initialen Änderungen eingecheckt werden mit: + These initial changes can then be checked in with: .. code-block:: console @@ -44,120 +43,117 @@ Git Best Practices $ git remote add origin ssh://git@github.com:veit/cusy.example.git $ git push -u origin master - Auch eine ``README.rst``-Datei sollte in jedem Repository vorhanden sein, in - der das Deployment und der grundsätzliche Aufbau des Codes beschrieben wird. + Each repository should also have a ``README.rst`` file that describes the + deployment and the basic structure of the code. -- Macht oft Commits! +- Commit often! - Dies erleichtert euch: + This makes it easier for you - - die Eingrenzung von Fehlern - - das Verständnis für den Code - - die zukünftige Wartung und Pflege. + - to isolate errors + - to understand the code + - to maintain the code in the future - Falls ihr doch einmal mehrere Änderungen an einer Datei durchgeführt habt, - könnt ihr diese auch später noch in mehrere Commits aufteilen mit: + If you have made several changes to a file, you can split them up into several + commits later with: .. code-block:: console $ git add -p my-changed-file.py -- Ändert nicht die veröffentlichte Historie! +- Don’t change the published history! + + Even if you later find out that a commit that has already been published with + ``git push`` contains one or more errors, you should never try to undo this + commit. Rather, you should fix the error that have occurred through further + commits. - Auch wenn ihr zu einem späteren Zeitpunkt herausfindet, dass ein Commit, der - mit ``git push`` bereits veröffentlicht wurde, einen oder mehrere Fehler - enthält, so solltet ihr dennoch niemals versuchen, diesen Commit ungeschehen zu - machen. Vielmehr solltest Du durch weitere Commits den oder die aufgetretenen - Fehler zu beheben. -- Wählt einen Git-Workflow! +- Choose a Git workflow! - Wählt einen Workflow, der am besten zu Eurem Projekt passt. Projekte sind - keineswegs identisch und ein Workflow, der zu einem Projekt passt, muss - nicht zwingend auch in einem anderen Projekt passen. Auch kann sich initial - ein anderer Workflow empfehlen als im weiteren Fortschritt des Projekts. + Choose a workflow that fits best to your project. Projects are by no means + identical and a workflow that fits one project does not necessarily have to + fit in another project. A different workflow can be recommended initially than + in the further progress of the project. -- Macht sinnvolle Commits! +- Make meaningful commits! - Mit dem Erstellen aufschlussreicher und beschreibender Commit-Nachrichten - erleichtert ihr die Arbeit im Team ungemein. Sie ermöglichen anderen, eure - Änderungen zu verstehen. Auch sind sie zu einem späteren Zeitpunkt hilfreich - um nachvollziehen zu können, welches Ziel mit dem Code erreicht werden - sollte. + By creating insightful and descriptive commit messages, you make working in a + team a lot easier. They allow others to understand your changes. They are also + helpful at a later point in time to understand which goal should be achieved + with the code. - Üblicherweise sollten kurze, 50–72 Zeichen lange Nachrichten angegeben - werden, die in einer Zeile ausgegeben werden, z.B. mit - ``git log --oneline``. + Usually short messages, 50–72 characters long, should be specified and + displayed on one line, eg with ``git log --oneline``. - Mit ``git blame`` könnt ihr euch auch später noch für jede Zeile angeben - lassen, in welcher Revision und von welchem Autor sie kam. Weitere - Informationen hierzu findet ihr in der Git-Dokumentation: `git-blame - `_. + With ``git blame`` you can later specify for each line in which revision and + by which author the change was made. You can find more information on this in + the Git documentation: `git-blame `_. - GitLab interpretiert bestimmte Commit-Nachrichten auch als Links interpretieren, z.B.: + GitLab also interprets certain commit messages as links, e.g. .. code-block:: console $ git commit -m "Awesome commit message (Fixes #21 and Closes group/otherproject#22)" - * zu Issues: ``#123`` + * links to issues: ``#123`` - * auch in anderen Projekten: ``othergroup/otherproject#123`` + * also for issues in other projects:: ``othergroup/otherproject#123`` - * zu Merge Requests: ``!123`` - * zu Snippets: ``$123`` + * links to merge requests: ``!123`` + * links to snippets: ``$123`` - Dabei sollte es zu jedem Commit mindestens ein Ticket geben, das - ausführlichere Hinweise zu den Änderungen geben sollte. + There should be at least one ticket for each commit that should provide more + detailed information about the changes. - Weitere gute Hinweise findet ihr in `A Note About Git Commit Messages + You can find more good information in `A Note About Git Commit Messages `_. -- Wartet euer Repository regelmäßig! +- Maintain your repository regularly! - Folgende Wartungsarbeiten solltet ihr regelmäßig durchführen: + You should perform the following maintenance work regularly: - - Validiert das Repo mit ``git fsck``. - - Komprimiert das Repo mit ``git gc`` bzw. ``git gc --aggressive``. + - Validate the repo with ``git fsck``. + - Compresses the repo with ``git gc`` or ``git gc --aggressive``. .. seealso:: * `git gc `_ * `Git Interna - Wartung und Datenwiederherstellung `_ - - Bereinigt die Remote Tracking Branches mit ``git remote update --prune``. - - Überprüft vergessene Arbeiten mit ``git stash list``. + - Clean up the remote tracking branches with ``git remote update --prune``. + - Checks forgotten work with ``git stash list``. -- Überprüft Eure Repositories regelmäßig auf unerwänschte Dateien! +- Check your repositories regularly for unwanted files! - Mit `Gitleaks `_ könnt Ihr Eure - Repositories regelmäßig auf ungewollt gespeicherte Zugangsdaten überprüfen. + With `Gitleaks `_ you can regularly + check your repositories for unintentionally saved access data. - Und mit `Git Filter-Branch `_, - `BFG Repo-Cleaner `_ oder - `git-filter-repo `_ könnt Ihr - unerwünschte Dateien, seien es Zugangsdaten oder große Binärdateien aus Eurer - Git-Historie entfernen. + With `Git Filter-Branch `_, + `BFG Repo-Cleaner `_ or + `git-filter-repo `_ you can remove + unwanted files, be it access data or large binary files, from your Git + history. - Alternativ könnt Ihr auch auf der Kommandozeile die Daten löschen. + Alternatively, you can also delete the data on the command line. - – Löschen des letzten Commits + – Delete the last commit .. code-block:: console $ git reset HEAD^ --hard $ git push origin -f - – Löschen anderer Commits + – Delete other commits .. code-block:: console $ git rebase -i sha origin ``-i`` - interaktiver Modus, in dem Euer Standardeditor geöffnet wird und eine - Liste aller Commits nach dem zu entfernenden Commit mit dem Hash-Wert - ``sha`` angezeigt wird, z.B.: + Interactive mode, in which your standard editor is opened and a list of + all commits after the commit with the hash value ``sha`` to be removed + is displayed, e.g. .. code-block:: console @@ -165,24 +161,21 @@ Git Best Practices pick 410266e Change import for the interface … - Wenn ihr nun eine Zeile entfernt, so wird dieser Commit nach dem - Speichern und Schließen des Editors gelöscht. Anschließend kann das - entfernte Repository aktualisiert werden mit: + If you now remove a line, this commit will be deleted after saving and + closing the editor. Then the remote repository can be updated with: .. code-block:: console - $ git push origin HEAD:master -f + $ git push origin HEAD:master -f - – Ändern einer Commit-Nachricht + – Modifying a commit message - Dies lässt sich ebenfalls einfach mit ``rebase`` realisieren wobei Ihr in - Ihrem Editor nicht die Zeile löschen sondern in der Zeile ``pick`` durch - ``r`` (*reword*) ersetzen müsst. + This can also be easily with ``rebase`` by not deleting the line in your + editor but replace ``pick`` with ``r`` (*reword*). - – Entfernen einer Datei aus der Historie + – Remove a file from the history - Eine Datei kann vollständig aus Git-Historie des aktuellen Branches entfernt - werden mit: + A file can be completely removed from the current branch’s Git history with: .. code-block:: console @@ -195,7 +188,7 @@ Git Best Practices $ git gc --aggressive --prune=now $ git push origin --force - – Entfernen einer Zeichenkette aus der Historie + – Removing a string from the history .. code-block:: console @@ -204,8 +197,8 @@ Git Best Practices … .. note:: - Bei macOS muss ``/usr/bin/true`` statt des ``/bin/true`` bei Linux - verwendet werden. + On macOS ``/usr/bin/true`` must be used instead of ``/bin/true`` on + Linux. .. seealso:: * `git-reflog `_ diff --git a/docs/productive/git/branching.rst b/docs/productive/git/branching.rst index e64dac22..db32268e 100644 --- a/docs/productive/git/branching.rst +++ b/docs/productive/git/branching.rst @@ -1,22 +1,21 @@ -Git-Verzweigungen -================= +Git branches +============ ``$ git branch [-a]`` - zeigt alle lokalen Verzweigungen in einem Repository an. + shows all local branches in a repository. ``-a`` - zeigt auch alle entfernten Verzweigungen an. + also shows all removed branches. ``$ git branch [branch_name]`` - erstellt auf Basis des aktuellen ``HEAD`` einen neuen Zweig. + creates a new branch based on the current ``HEAD``. ``$ git checkout [-b] [branch_name]`` - ändert das Arbeitsverzeichnis in den angegebenen Zweig. + changes the working directory to the specified branch. ``-b`` - erstellt den angegebenen Zweig, wenn dieser nicht schon besteht. + creates the specified branch if it does not already exist. ``$ git merge [from name]`` - verbindet den angegebenen mit dem aktuellen Zweig, in dem Ihr euch gerade - befindet, z.B.: + connects the given branch with the current branch you are currently in, e.g. .. code-block:: console @@ -28,10 +27,10 @@ Git-Verzweigungen 1 files changed, 0 insertions(+), 1 deletions(-) ``Fast forward`` - besagt, dass der neue Commit direkt auf den ursprünglichen Commit folgte - und somit der Zeiger (*branch pointer*) nur weitergeführt werden musste. + means that the new commit immediately followed the original commit and + so the branch pointer only had to be continued. - In anderen Fällen kann die Ausgabe z.B. so aussehen: + In other cases the output can look like this: .. code-block:: console @@ -42,13 +41,13 @@ Git-Verzweigungen 1 files changed, 1 insertions(+), 0 deletions(-) ``recursive`` - ist eine Merge-Strategie, die verwendet wird, sofern die Zusammenführung - nur zu ``HEAD`` erfolgt. + is a merge strategy that is used when the merge is only to be done to + ``HEAD``. -Merge-Konflikte ---------------- +Merge conflict +-------------- -Gelegentlich stößt Git beim Zusammenführen jedoch auf Probleme, z.B.: +Occasionally, however, Git runs into issues with merging, such as: .. code-block:: console @@ -64,15 +63,14 @@ Gelegentlich stößt Git beim Zusammenführen jedoch auf Probleme, z.B.: * `Git Tools - Fortgeschrittenes Merging `_ -Verzweigungen (Branches) ------------------------- +Branches +-------- ``$ git branch -d [name]`` - löscht den ausgewählten Zweig, wenn er bereits in einen anderen überführt - wurde. + deletes the selected branch if it has already been transferred to another. - ``-D`` statt ``-d`` erzwingt die Löschung. + ``-D`` instead of ``-d`` forcing the deletion. .. seealso:: - * `Git Branching - Branches auf einen Blick - `_ + * `Git Branching - Branches in a Nutshell + `_ diff --git a/docs/productive/git/glossary.rst b/docs/productive/git/glossary.rst index 5c650732..c017465b 100644 --- a/docs/productive/git/glossary.rst +++ b/docs/productive/git/glossary.rst @@ -1,41 +1,37 @@ -Git-Glossar -=========== +Git glossary +============ .. glossary:: Git - Git ist eine verteilte Versionsverwaltung + Git is a distributed version control system. GitLab - Web-Anwendung zur Versionsverwaltung auf Basis von :term:`git`. Später - kamen Gitlab CI, ein System zur kontinuierlichen Integration, GitLab - Runner, Container-Registry und vieles andere hinzu. + Web application for version management based on :term:`git`. RGitlab CI, + a system for continuous integration, GitLab Runner, container registry + and much more were added later. ``git commit`` - ein Snapshot des gesamten Git-Repository, komprimiert in einem `SHA + a snapshot of the entire Git repository, compressed in a `SHA `_ ``branch`` - ein leichtgewichtiger beweglicher Zeiger auf einen Commit + a lightweight moving pointer to a commit ``clone`` - lokale Version eines Repository einschließlich aller Commits und - Branches + local version of a repository including all commits and branches ``remote`` - gemeinsames Repository, z.B. auf GitLab, zum Austausch der Änderungen - in einem Team + shared repository, e.g. on GitLab, for exchanging changes in a team ``fork`` - Kopie eines Repository auf GitLab, die einem anderen Nutzer gehört + Copy of a repository on GitLab that belongs to another user Merge request - Ort zum Vergleichen und Diskuttieren der in einem Branch eingeführten - Änderungen mit Bewertungen, Kommentaren, Tests etc.; siehe auch - `Merge requests + Place to compare and discuss the changes introduced in a branch with + ratings, comments, tests etc.; see also `Merge requests `_. ``HEAD`` - Der ``HEAD``-Zeiger repräsentiert Euer aktuelles Arbeitsverzeichnis und - kann mit ``git checkout`` in verschiedene Zweige, Tags oder Commits - verschoben werden + The ``HEAD`` pointer represents your current working directory and can + be moved to different branches, tags or commits with ``git checkout``. diff --git a/docs/productive/git/index.rst b/docs/productive/git/index.rst index 5afbf7a0..4061cf60 100644 --- a/docs/productive/git/index.rst +++ b/docs/productive/git/index.rst @@ -1,12 +1,11 @@ -Code verwalten mit Git -====================== +Manage code with Git +==================== -Um eine bessere Kontrolle über Euren Quellcode zu erhalten, wird dieser -üblicherweise mit `Git `_ verwaltet. Hier werde ich jedoch -nur kurz die :doc:`wichtigsten Begriffe ` erläutern und eine kurze -:doc:`Installations- und Konfigurationsanleitung ` geben. -Allgemeine Einführungen in Git sind an anderer Stelle schon hinreichend -vorhanden. +In order to have better control over your source code, it is usually managed +with `Git `. However, I will only briefly explain the +most important terms and provide brief :doc:`installation and configuration +instructions `. General introductions to Git are sufficiently +available elsewhere. .. seealso:: @@ -16,9 +15,9 @@ vorhanden. * :download:`Git Cheat Sheet (PDF) ` * `Git reference `_ -Im Wesentlichen zeige ich in diesem Tutorial einerseits, wie :doc:`Jupyter Notebooks -` sinnvoll mit Git verwaltet lassen, und andererseits -:doc:`Best Practices ` und typische :doc:`workflows/index`. +Essentially, in this tutorial, I show on the one hand how :doc:`Jupyter +Notebooks ` can be managed with Git, and on the other hand +:doc:`best practices ` and typical :doc:`workflows/index`. .. toctree:: :hidden: diff --git a/docs/productive/git/install-config.rst b/docs/productive/git/install-config.rst index 3bfab6b5..79907d80 100644 --- a/docs/productive/git/install-config.rst +++ b/docs/productive/git/install-config.rst @@ -1,62 +1,61 @@ -Git-Installation und -Konfiguration -=================================== +Git installation and configuration +================================== Installation ------------ -Für iX-Distributionen sollte Git im Standard-Repository vorhanden sein. +For iX distributions, Git should be in the standard repository. -* Für Debian/Ubuntu: +* For Debian/Ubuntu: .. code-block:: console $ sudo apt install git-all - Mit der Bash-Autovervollständigung lässt sich Git auf der Kommandozeile - einfacher bedienen: + The bash autocompletion makes Git easier to use on the command line: .. code-block:: console $ sudo apt install bash-completion -* Für macOS: +* For macOS: - Es gibt verschiedene Möglichkeiten, Git auf einem Mac zu installieren. Am - einfachsten ist es vermutlich, die Xcode Command Line Tools zu installieren. - Hierfür müsst Ihr nur ``git`` das erste Mal vom Terminal aufrufen: + There are several different ways to install Git on a Mac. Probably the easiest + eay to do is to install the Xcode Command Line Tools. For this you only have + to call up ``git`` in the terminal for the first time: .. code-block:: console $ git --version - ``git-completion`` könnt Ihr mit `Homebrew `_ installieren: + ``git-completion`` you can install with `Homebrew `_: - Anschließend müsst Ihr folgende Zeile in ``~/.bash_profile`` hinzufügen: + Then you have to add the following line in ``~/.bash_profile``: .. code-block:: bash [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh" -* Für Windows: +* For Windows: - Ihr könnt einfach https://git-scm.com/download/win aufrufen um den Download - automatisch zu starten. Weitere Informationen findet Ihr unter + You can simply go to https://git-scm.com/download/win to start the download + automatically. Further information can be found at https://gitforwindows.org/. -Konfiguration +Configuration ------------- ``$ git config --global user.name "[name]"`` - legt den Namen fest, den mit Euren Commit-Transaktionen verknüpft wird. + defines the name associated with your commit transactions. ``$ git config --global user.email "[email address]"`` - legt die E-Mail fest, die mit Euren Commit-Transaktionen verknüpft wird. + defines the email that will be linked to your commit transactions. ``$ git config --global color.ui auto`` - aktiviert die Kolorierung der Befehlszeilenausgabe. + activates the coloring of the command line output. -Die ``~/.gitconfig``-Datei -~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``~/.gitconfig`` file +~~~~~~~~~~~~~~~~~~~~~~~~~ -Mit den oben angegebenen Befehle kann z.B. folgende Datei erstellt werden: +For example, the following file can be created with the commands given above: .. code-block:: ini @@ -69,7 +68,7 @@ Mit den oben angegebenen Befehle kann z.B. folgende Datei erstellt werden: status = auto branch = auto -In der ``~/.gitconfig``-Datei können jedoch auch Aliase festgelegt werden: +However, aliases can also be specified in the ``~/.gitconfig`` file: .. code-block:: ini @@ -81,8 +80,8 @@ In der ``~/.gitconfig``-Datei können jedoch auch Aliase festgelegt werden: df = diff dfs = diff --staged -Auch der Editor lässt sich angeben und die Hervorhebung von Leerzeichenfehlern -in ``git diff``: +The editor can also be specified and space errors can be highlighted in ``git +diff``: .. code-block:: ini @@ -93,19 +92,19 @@ in ``git diff``: # Highlight whitespace errors in git diff: whitespace = tabwidth=4,tab-in-indent,cr-at-eol,trailing-space -Anmeldedaten verwalten -:::::::::::::::::::::: +Manage login data +::::::::::::::::: -Seit der Git-Version 1.7.9 lassen sich die Zugangsdaten zu git-Repositories mit -`gitcredentials `_ verwalten. Um diese -zu nutzen, könnt Ihr z.B. folgendes angeben: +Since Git version 1.7.9, the access data to git repositories can be managed with +`gitcredentials `_. To use this, you +can, for example, specify the following: .. code-block:: console $ git config --global credential.helper Cache -Hiermit wird Ihr Passwort für 15 Minuten im Cache-Speicher gehalten. Der Timeout -kann ggf. erhöht werden, z.B. mit: +This will keep your password in the cache for 15 minutes. The timeout can be +increased if necessary, e.g. with: .. code-block:: console @@ -114,10 +113,9 @@ kann ggf. erhöht werden, z.B. mit: macOS ::::: -Unter macOS lässt sich mit `osxkeychain` die Schlüsselbundverwaltung -(*Keychain*) nutzen um die Zugangsdaten zu speichern. `osxkeychain` setzt Git in -der Version 1.7.10 oder neuer voraus und kann im selben Verzeichnis wie Git -installiert werden mit: +With macOS you can use `osxkeychain` to store the login information. +`osxkeychain` requires Git version 1.7.10 or newer and can be installed in the +same directory as Git with: .. code-block:: console @@ -129,7 +127,7 @@ installiert werden mit: Password: git config --global credential.helper osxkeychain -Dies trägt folgendes in die ~/.gitconfig ein: +This enters the following in the `~/.gitconfig` file: .. code-block:: ini @@ -139,25 +137,24 @@ Dies trägt folgendes in die ~/.gitconfig ein: Windows ::::::: -Für Windows steht `Git Credential Manager for Windows -`_ zur -Verfügung. Für das Programm muss der `Installer +For Windows `Git Credential Manager for Windows +`_ is +available. First the `Installer `_ -heruntergeladen werden. Nach dem Doppelklick führt er Euch durch die weitere -Installation. Als Terminal-Emulator für Git Bash solltet Ihr das -Standardkonsolenfenster von Windows auswählen. +must be downloaded for the program. After double-clicking, it will guide you +through the rest of the installation. As a terminal emulator for Git, you should +select the standard Windows console window. .. note:: - Ein umfangreiches Beispiel einer `~/.gitconfig`-Datei findet Ihr in meinem - `dotfiles `_-Repository: `.gitconfig + You can find a comprehensive example of a `~/.gitconfig` file in my + `dotfiles `_ repository: `.gitconfig `_. -Die ``.gitgnore``-Datei -~~~~~~~~~~~~~~~~~~~~~~~ +The ``.gitgnore`` file +~~~~~~~~~~~~~~~~~~~~~~ -In der ``.gitgnore``-Datei eines Repository könnt Ihr Dateien von der -Versionsverwaltung ausschließen. Eine typische ``.gitgnore``-Datei kann z.B. so -aussehen: +In the ``.gitgnore`` file you can exclude files from version management. A +typical ``.gitgnore`` file can look like this: .. code-block:: ini @@ -166,18 +163,18 @@ aussehen: /tmp *.swp -Git-commit leerer Ordner -:::::::::::::::::::::::: +Git-commit empty folder +::::::::::::::::::::::: -In obigem Beispiel seht Ihr, dass mit ``/logs/*`` keine Inhalte des -``logs``-Verzeichnis mit Git versioniert werden soll, in der Folgezeile jedoch -eine Ausnahme definiert wird: ``!logs/.gitkeep`` erlaubt, dass die Datei -``.gitkeep`` mit Git verwaltet werden darf. Damit wird dann auch das -``logs``-Verzeichnis in das Git-Repository übernommen. Diese Hilfskonstruktion -ist erforderlich, da leere Ordner nicht mit Git verwaltet werden können. +In the example above you can see that with ``/logs/*`` no content of the +``logs`` directory should be versioned with Git, but an exception is defined in +the following line: ``!logs/.gitkeep`` allows the file ``.gitkeep`` to be +managed with Git. The ``logs`` directory is then also transferred to the Git +repository. This construction is necessary because empty folders cannot be +managed with Git. -Eine andere Möglichkeit besteht darin, in einem leeren Ordner eine -``.gitignore``-Datei mit folgendem Inahlt zu erstellen: +Another possibility is to create a ``.gitignore`` file in an empty folder with +the following content: .. code-block:: ini @@ -193,8 +190,8 @@ Eine andere Möglichkeit besteht darin, in einem leeren Ordner eine ``excludesfile`` :::::::::::::::: -Ih könnt jedoch auch zentral für alle Git-Repositories Dateien ausschließen. -Hierfür wird üblicherweise in der ``~/.gitconfig``-Datei folgendes angegeben: +However, you can also exclude files centrally for all Git repositories. For this +purpose, you can set ``excludesfile`` in the ``~/.gitconfig`` file: .. code-block:: ini @@ -205,6 +202,6 @@ Hierfür wird üblicherweise in der ``~/.gitconfig``-Datei folgendes angegeben: … .. note:: - Hilfreiche Vorlagen findet Ihr in meinem `dotfiles - `_-Repository oder - auf der Website `gitignore.io `_. + You can find helpful templates in my `dotfiles + `_ repository or + on the `gitignore.io `_ website. diff --git a/docs/productive/git/jupyter-config.rst b/docs/productive/git/jupyter-config.rst index 28fba230..fcf8e2a6 100644 --- a/docs/productive/git/jupyter-config.rst +++ b/docs/productive/git/jupyter-config.rst @@ -1,42 +1,39 @@ -Git für Jupyter Notebooks konfigurieren -======================================= - -Im Notebook-Dateiformat :ref:`nbformat ` können auch -die Ergebnisse der Berechnungen gespeichert werden. Dies können auch -Base-64-codierte Blobs für Bilder und andere Binärdaten sein, die üblicherweise -nicht in eine Versionsverwaltung übernommen werden sollen. Diese können zwar -manuell entfernt werden mit :menuselection:`Cell --> All Output --> Clear`, ihr -müsst diese Schritte jedoch vor jedem ``git add`` ausführen, und es löst auch -eine zweite Ursache für das Rauschen in ``git diff`` nicht, nämlich dasjeinige -in den `Metadaten +Configuring Git for Jupyter Notebooks +===================================== + +The results of the calculations can also be saved in the notebook file format +:ref:`nbformat `. These can also be Base-64-coded blobs +for images and other binary data that should not normally be included in a +version management. These can be removed manually with :menuselection:`Cell --> +All Output --> Clear`, but you have to carry out these steps before every ``git +add``, and it also does not solve a second cause of the noise in ``git diff``, +namely some in the `metadata `_. -Um nun systematisch vergleichbare Versionen von Notebooks in der -Versionsverwaltung zu erhalten, können wir `jq -`_ verwenden, einen leichtgewichtigen -JSON-Prozessor. Zwar benötigt man einige Zeit um ``jq`` einzurichten da es -eine eigene eine eigene Abfrage-/Filtersprache mitbringt, aber meist sind -schon die Standardeinstellungen gut gewählt. +In order to get systematically comparable versions of notebooks in the version +management, we can use `jq `_, a lightweight +JSON processor. It takes some time to set up ``jq`` because it has its own +query/filter language, but the default settings are usually well chosen. Installation ------------ -``jq`` für Debian/Ubuntu kann installiert werden mit: +``jq`` for Debian/Ubuntu can be installed with: .. code-block:: console $ sudo apt install jq -oder für macOS mit: +or for macOS with: .. code-block:: console $ brew install jq -Beispiel --------- +Example +------- -Ein typischer Aufruf ist: +A typical call is: .. code-block:: console @@ -44,23 +41,21 @@ Ein typischer Aufruf ist: '(.cells [] | select (has ("output")) | .outputs) = [] | (.cells [] | select (has ("execution_count")) | .execution_count) = null | .metadata = {"language_info": {"name": "python", "pygments_lexer": "ipython3"}} - | .Cells []. Metadaten = {} + | .Cells []. metadata = {} ' example.ipynb -Jede Zeile innerhalb der einfachen Anführungszeichen definiert einen Filter – -die erste wählt alle Einträge aus der Liste *cells* aus und löscht die Ausgaben. -Der nächste Eintrag setzt alle Ausgaben zurück. Der dritte Schritt löscht die -Metadaten des Notebooks und ersetzt sie durch ein Minimum an erforderlichen -Informationen, damit das Notebook noch ohne Beanstandungen ausgeführt werden -kann, folgendes eingeben:wenn es mit nbsphinx formatiert sind. Die vierte Filterzeile, -``.cells []. metadata = {}``, löscht alle Metainformationen. Falls ihr bestimmte -Metainformationen beibehalten wollt, könnt ihr dies hier angeben. +Each line within the single quotation marks defines a filter – the first selects +all entries from the cells list and deletes the output. The next entry resets all +outputs. The third step deletes the notebook’s metadata and replaces it with a +minimum of necessary information so that the notebook can still be run without +complaints. The fourth filter line ``.cells []. metadata = {}``, deletes all meta +information. If you want to keep certain meta information, you can indicate this +here. -Einrichten ----------- +Set up +------ -#. Um euch die Arbeit zu erleichtern, könnt ihr einen Alias in der - ``~/.bashrc``-Datei anlegen: +#. To make your work easier, you can create an alias in the ``~/.bashrc`` file: .. code-block:: bash @@ -71,23 +66,22 @@ Einrichten | .cells[].metadata = {} \ '" -#. Anschließend könnt ihr bequem im Terminal folgendes eingeben: +#. Then you can conveniently enter the following in the terminal: .. code-block:: console $ nbstrip_jq example.ipynb > stripped.ipynb -#. Wenn ihr von einem bereits vorhandenen Notebook ausgeht, solltet ihr zunächst - einen ``filter``-Commit hinzufügen, indem ihr einfach die neu gefilterte - Version eures Notebooks ohne die unerwünschten Metadaten einlest. Nachdem ihr - mit ``git add`` das Notebook hinzugefügt habt, könnt ihr mit - ``git diff --cached`` schauen, ob der Filter auch wirklich gewirkt hat bevor - ihr dann ``git commit -m 'filter'`` angebt. +#. If you start with an already existing notebook, you should first add a + ``filter`` commit by simply reading in the newly filtered version of your + notebook without the unwanted metadata. After you have added the notebook + with ``git add``, you can see whether the filter has really worked with + ``git diff --cached`` before you do ``git commit -m 'filter'``. -#. Wenn ihr diesen Filter für alle Git-Repositories verwenden wollt, könnt ihr - euer Git auch global konfigurieren: +#. If you want to use this filter for all Git repositories, you can also + configure your Git globally: - #. Zunächst fügt ihr in ``~/.gitconfig`` folgendes hinzu: + #. First you add the following to your ``~/.gitconfig`` file: .. code-block:: ini @@ -104,21 +98,21 @@ Einrichten smudge = cat required = true - #. Anschließend müsst ihr in ``~/.gitattribute`` nur noch folgendes angeben: + #. Then you have to specify the following in the ``~/.gitattribute`` file: .. code-block:: ini *.ipynb filter=nbstrip_jq .. warning:: - Wenn ihr ``git rebase`` durchführen wollt, solltet ihr vorher die Zeile - deaktivieren. - -#. Dennoch bleibt das Problem, dass ``git status`` Änderungen an Dateien - anzeigt wenn die Zellen eines Notebook ausgeführt wurden, und dies obwohl - ``git diff`` weiterhin keine Änderungen anzeigt. Daher sollte in der - ``~/.bashrc``-Datei folgendes eingetragen um schnell das jeweilige - Arbeitsverzeichnis reinigen zu können: + If you want to do ``git rebase``, you should deactivate the line + beforehand. + +#. However, the problem remains that ``git status`` show changes to files when + the cells of a notebook have been executed, even though ``git diff`` still + shows no changes. Therefore the following should be entered in the + ``~/.bashrc`` file in order to quickly clean the respective working + directory: .. code-block:: bash diff --git a/docs/productive/git/log.rst b/docs/productive/git/log.rst index dd39014a..094575ae 100644 --- a/docs/productive/git/log.rst +++ b/docs/productive/git/log.rst @@ -1,52 +1,51 @@ -Git Log +Git log ======= ``$ git log [-n count]`` - auflisten der Commit-Historie des aktuellen Zweiges. + list the commit history of the current branch. ``-n`` - beschränkt die Anzahl der Commits auf die angegebene Zahl. + limits the number of commits to the specified number. ``$ git log [--after="YYYY-MM-DD"] [--before="YYYY-MM-DD"]`` - Commit-Historie gefiltert nach Datum. + Commit history filtered by date. - Auch relative Angaben wie ``1 week ago`` oder ``yesterday`` sind zulässig. + Relative information such as ``1 week ago`` or ``yesterday`` is also + permitted. ``$ git log --author = "name"`` - filtert die Commit-Historie nach Autor*innenen. + filters the commit history by authors. - Es kann auch nach mehreren Autor*innen gleichzeitig gesucht werden, z.B.: + You can also search for several authors at the same time, e.g. ``$ git log --author="veit\|vsc"`` ``$ git log --grep = "term"`` - filtert die Commit-Historie nach regulären Ausdrücken in der - Commit-Nachricht. + filters the commit history for regular expressions in the commit message. ``$ git log -S"foo"`` - filtert Commits nach bestimmten Zeilen im Quellcode. + filters commits according to certain lines in the source code. ``$ git log -G"ba*"`` - filtert Commits nach regulären Ausdrücken im Quellcode. + filters commits based on regular expressions in the source code. ``$ git log - path/to/foo.py`` - filtert die Commit-Historie nach bestimmten Dateien. + filters the commit history for specific files. ``$ git log master..feature`` - filtert nach unterschiedlichen Commits in verschiedenen Zweigen (Branches), - in unserem Fall zwischen den Branches ``master`` und ``feature``. + filters for different commits in different branches, in our case between the + branches ``master`` and ``feature``. ``$ git log --oneline --graph --decorate`` - anzeigen des Verlaufsdiagramms mit Referenzen, ein Commit pro Zeile. + Show the history diagram with references, one commit per line. ``$ git log ref..`` - Commits auflisten, die im aktuellen Zweig vorhanden sind und nicht in - ``ref`` zusammengeführt werden. ``ref`` kann dabei der Name eines Zweigs - oder eines Tag sein. + List commits that exist in the current branch and are not merged into + ``ref``. ``ref`` can be the name of a branch or a tag. ``$ git log ..ref`` - Commits auflisten, die in ``ref`` vorhanden sind und nicht mit dem aktuellen - Zweig zusammengeführt werden. + List commits that exist in ``ref`` and are not merged with the current + branch. ``$ git reflog`` - Vorgänge (z.B. ``checkout``, ``commit``) auflisten, die im lokalen - Repository ausgeführt wurden. + List operations (e.g. ``checkout``, ``commit``) that have been performed in + the local repository. diff --git a/docs/productive/git/pre-commit.rst b/docs/productive/git/pre-commit.rst index a61a1f61..49b4d573 100644 --- a/docs/productive/git/pre-commit.rst +++ b/docs/productive/git/pre-commit.rst @@ -1,53 +1,49 @@ -Git pre-commit Hooks +Git pre-commit hooks ==================== -`pre-commit `_ ist ein Framework zum Verwalten und -Pflegen mehrsprachiger pre-commit-Hooks. +`pre-commit `_ is a framework for managing and +maintaining multilingual pre-commit hooks. -Eine wesentliche Aufgabe ist es, dem gesamten Entwicklungsteam dieselben Skripte -zur Verfügung zu stellen. `pre-commit `_ von yelp -verwaltet solche pre-commit-Hooks und verteilt sie auf verschiedene Projekte und -Entwickler. +An essential task is to make the same scripts available to the entire +development team. Yelp’s `pre-commit `_ manages such +pre-commit hooks and distributes them to various projects and developers. -Git pre-commit Hooks werden meist verwendet um vor Code Reviews automatisch auf -Probleme im Code hinzuweisen, z.B. um die Formattierung zu überprüfen oder -Debug-Anweisungen zu finden. Pre-Commit vereinfacht das projektübergreifende -Teilen vom Pre-Commit-Hooks. Dabei ist auch die Sprache, in der z.B. ein Linter -geschrieben wurde, wegabstrahiert – so ist ``scss-lint`` in Ruby geschrieben, -Ihr könnt ihn jedoch mit Pre-Commit verwenden ohne Eurem Projekt ein Gemfile -hinzufügen zu müssen. +Git pre-commit hooks are mostly used to automatically point out problems in the +code before code reviews, e.g. to check the formatting or to find debug +instructions. Pre-commit simplifies the cross-project sharing of the pre-commit +hook. The language in which a linter was written, for example, is also +abstracted away – ``scss-lint`` is written in Ruby, but you can use it with +pre-commit without having to add a gem file to your project. Installation ------------ -Bevor Ihr Hooks ausführen könnt, muss der pre-commit-Paketmanager installiert -sein. +Before you can hook the pre-commit package manager must be installed. -… auf macOS: +… on macOS: .. code-block:: console $ brew install pre-commit -… in Eurem Python-Projekt: +… in your Python project: .. code-block:: console $ pipenv install pre-commit -Überprüfen der Installation z.B. mit +Check the installation with, for example .. code-block:: console $ pipenv run pre-commit -V pre-commit 2.6.0 -Konfiguration +Configuration ------------- -Nachdem Pre-Commit installiert ist, können mit der ``.pre-commit- -config.yaml``-Datei im Root-Verzeichnis Eures Projekts Plugins für dieses -Projekt konfiguriert werden. +After pre-commit has been installed, plugins for this project can be configured +with the ``.pre-commit-config.yaml`` file in the root directory of your project. .. code-block:: yaml @@ -63,7 +59,7 @@ Projekt konfiguriert werden. hooks: - id: black -Ihr könnt Euch diese Datei auch generieren lassen mit +You can also have this file generated with .. code-block:: console @@ -79,15 +75,13 @@ Ihr könnt Euch diese Datei auch generieren lassen mit - id: check-yaml - id: check-added-large-files -Wenn Ihr diesen pre-commit-Hook vor jedem commit ausführen möchtet, installiert -diesen mit ``pre-commit install``. Sollen die Hooks manuell ausgeführt werden, -kann dies mit ``pre-commit run --all-files`` geschehen. Einzelne Hooks können -dann auch separat ausgeführt werden, z.B. ``pre-commit run -trailing-whitespace``. +If you want to run this pre-commit hook before every commit, install it with +``pre-commit install``. If the hooks are to be executed manually, this can be +done with ``pre-commit run --all-files``. Single hooks can then also be carried +out separately, for example ``pre-commit run trailing-whitespace``. -Beim ersten Aufruf eines pre-commit-Hooks wird dieser zunächst heruntergeladen -und anschließend installiert. Dies kann einige Zeit benötigen, z.B. wenn eine -Kopie von ``node`` erstellt werden muss. +The first time a pre-commit hook is called, it is first downloaded and then +installed. This can take some time, e.g. if a copy of ``node`` has to be made. .. code-block:: console @@ -98,40 +92,40 @@ Kopie von ``node`` erstellt werden muss. Check for added large files..............................................Passed black....................................................................Passed -Eine vollständige Liste der Konfigurationsoptionen erhaltet Ihr in `Adding pre-commit -plugins to your project +A full list of configuration options can be found in `Adding pre-commit plugins +to your project `_. -Ihr könnt auch eigene Hooks schreiben, siehe `Creating new hooks +You can also write your own hooks, see `Creating new hooks `_. -Ihr könnt die Hooks auch automatisch aktualisieren mit: +You can also update the hooks automatically with: .. code-block:: console $ pipenv run pre-commit autoupdate -Weitere Optionen findet Ihr unter `pre-commit autoupdate [options] +Further options can be found in `pre-commit autoupdate [options] `_. -Installieren der Git-Hook-Skripte -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Install the Git-Hook scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Damit Pre-Commit auch vor jedem Commit zuverlässig ausgeführt wird, werden die -Skripte in unserem Projekt installiert: +The scripts are installed in our project so that pre-commit is reliably executed +before each commit: .. code-block:: console $ pre-commit install pre-commit installed at .git/hooks/pre-commit -Verwenden in CI ---------------- +Use in CI +--------- -Pre-Commit kann auch für Continuous Integration verwendet werden. +Pre-commit can also be used for continuous integration. -Beispiel für GitHub Actions -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example of GitHub Actions +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: yaml @@ -146,8 +140,8 @@ Beispiel für GitHub Actions `pre-commit/action `_ -Beispiel für GitLab Actions -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example for GitLab Actions +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: yaml @@ -160,6 +154,5 @@ Beispiel für GitLab Actions .. seealso:: - Weitere Informationen zur Feinabstimmung des Caching findet Ihr in `Good - caching practices + For more information on fine-tuning caching, see `Good caching practices `_. diff --git a/docs/productive/git/reverting.rst b/docs/productive/git/reverting.rst index 0e7c7bf9..9cae8376 100644 --- a/docs/productive/git/reverting.rst +++ b/docs/productive/git/reverting.rst @@ -1,30 +1,30 @@ -Änderungen zurücknehmen -======================= +Undo changes +============ ``$ git reset [--hard] [target reference]`` - wechselt vom aktuellen Zweig zur Zielreferenz und hinterlässt den Unterschied - als nicht festgeschriebene Änderung, z.B.: + switches from the current branch to the target reference and leaves the + difference as an uncommitted change, e.g. .. code-block:: console $ git reset HEAD setup.py - ``--hard`` verwirft alle Änderungen. + ``--hard`` discards all changes. ``$ git revert [commit sha]`` - erstellt einen neuen Commit und nimmt die Änderungen des angegebenen Commits - zurück. Die Änderungen werden invertiert. + creates a new commit and undoes the changes to the specified commit. The + changes are inverted. ``$ git fetch [remote]`` - übernimmt die Änderungen von Remote, aktualisiert jedoch nicht die Zweige. + accepts changes from remote but does not update branches. ``$ git fetch --prune [remote]`` - Remote-Refs werden entfernt wenn sie im Remote-Repository entfernt wurden. + Remote refs are removed when they are removed from the remote repository. ``$ git pull [remote]`` - ruft Änderungen aus dem Remote-Repository ab und führt den aktuellen Zweig - mit dem Upstream zusammen. + pulls changes from the remote repository and merges the current branch with + the upstream. ``$ git push [--tags] [remote]`` - überträgt lokale Änderungen nach Remote. + transfers local changes to remote. - Mit ``--tags`` können gleichzeitig Tags übertragen werden. + With ``--tags`` tags can be transmitted at the same time. ``$ git push -u [remote] [branch]`` - überträgt den lokalen Zweig in das Remote-Repository wobei die Kopie als - Upstream festgelegt wird. + transfers the local branch to the remote repository with the copy set as + upstream. diff --git a/docs/productive/git/tagging.rst b/docs/productive/git/tagging.rst index 9121fc90..f71985b3 100644 --- a/docs/productive/git/tagging.rst +++ b/docs/productive/git/tagging.rst @@ -1,8 +1,8 @@ -Git-Tagging +Git tagging =========== ``$ git tag`` - auflisten aller Tags, z.B.: + list all tags, e.g. .. code-block:: console @@ -18,15 +18,15 @@ Git-Tagging 0.6.1 ``$ git tag -l regex`` - listet nur Tags auf, die zu einem regulären Ausdruck passen. + only lists tags that match a regular expression. ``$ git tag [name] [commit sha]`` - erstellt einen Tag mit dem Namen ``name`` für den aktuellen Commit. + creates a tag with the name ``name`` for the current commit. - Mit ``sha`` erhält der spezifische Commit einen Tag, nicht der aktuelle. + With ``sha`` the specific commit gets a tag, not the current one. ``$ git tag -a [name] [commit sha] [-m 'Commit message']`` - erstellt einen Tag mit dem Namen ``name`` für den aktuellen Commit, z.B.: + creates a tag with the name ``name`` for the current commit, e.g.: .. code-block:: console @@ -39,7 +39,7 @@ Git-Tagging * [new tag] 0.6.1 -> 0.6.1 ``git tag [-d name]`` - löschen eines Tag, z.B.: + delete a tag, e.g. .. code-block:: console diff --git a/docs/productive/git/tools.rst b/docs/productive/git/tools.rst index 35f59fde..aa12ac93 100644 --- a/docs/productive/git/tools.rst +++ b/docs/productive/git/tools.rst @@ -1,22 +1,21 @@ -Git-Tools für Notebooks +Git tools for notebooks ======================= ``nbdime`` ---------- -`nbdime `_ ist ein GUI für `nbformat -`_-Diffs und ersetzt `nbdiff -`_. Es versucht *Content-Aware*-Diffing -sowie das Merging von Notebooks, beschränkt sich nicht nur auf die Darstellung -von Diffs, sondern verhindert auch, dass unnötige Änderungen eingecheckt werden. +`nbdime `_ is a GUI for diffs of `nbformat +`_ and replaces `nbdiff +`_. It tries content-aware diffing as well +as the merging of notebooks, is not limited to the display of diffs, but also +prevents unnecessary changes from being checked in. .. _nbstripout_label: ``nbstripout`` -------------- -`nbstripout `_ automatisiert *Clear all -outputs*. Es nutzt `nbformat `_ und ein paar -Automagien um ``git config`` einzurichten. Meines Erachtens hat es jedoch zwei -Nachteile: es beschränkt sich auf den problematischen Metadaten-Abschnitt und -es ist langsam. +`nbstripout `_ automates *Clear all +outputs*. It uses `nbformat `_ and a few auto +magic to set up ``.git config``. In my opinion, however, it has two drawbacks: +it is limited to the problematic metadata section, and it is slow. diff --git a/docs/productive/git/work.rst b/docs/productive/git/work.rst index 4bdf7bed..a6586d8f 100644 --- a/docs/productive/git/work.rst +++ b/docs/productive/git/work.rst @@ -1,69 +1,70 @@ -Mit Git arbeiten +Working with Git ================ -Die Arbeit an einem Projekt beginnen ------------------------------------- +Start working on a project +-------------------------- -Ein eigenes Projekt starten -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Start your own project +~~~~~~~~~~~~~~~~~~~~~~ ``$ git init [my_project]`` - erstellt ein neues, lokales Git-Repository + creates a new, local git repository ``[my_project]`` - wenn der Projektname angegeben wird, erzeugt Git ein neues Verzeichnis - und initialisiert es + if the project name is given, Git creates a new directory and + initializes it - Wird kein Projektname angegeben, wird das aktuelle Verzeichnis - initialisiert + If no project name is given, the current directory is initialised -An einem Projekt mitarbeiten -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Work on a project +~~~~~~~~~~~~~~~~~ ``$ git clone [project_url]`` - lädt ein Projekt mit allen Zweigen (engl.: branches) und der gesamten - Historie vom entfernten Repository herunter + downloads a project with all branches and the entire history from the remote + repository ``--depth`` - gibt die Anzahl der Commits an, die heruntergeladen werden sollen + indicates the number of commits to be downloaded ``-b`` - gibt den Namen des entfernten Zweigs an, der heruntergeladen werden soll + specifies the name of the remote branch to be downloaded -An einem Projekt arbeiten -------------------------- +Work on a project +----------------- ``$ git status`` - zeigt den Status des aktuellen Zweiges im Arbeitsverzeichnisses an mit - neuen, geänderten und bereits zum Commit vorgemerkten Dateien. + shows the status of the current branch in the working directory with new, + changed and files already marked for commit. ``$ git add [file]`` - fügt eine Datei dem Bühnenbereich hinzu. + adds a file to the stage area. ``$ git add -p [file]`` - fügt Teile einer Datei dem Bühnenbereich hinzu. + adds parts of a file to the stage area. ``$ git add -e [file]`` - die zu übernehmenden Änderungen können im Standardeditor bearbeitet werden. + the changes to be adopted can be edited in the standard editor. ``$ git diff [file]`` - zeigt Unterschiede zwischen Arbeits- und Bühnenbereich. + shows differences between work and stage areas. ``$ git diff --staged [file]`` - zeigt Unterschiede zwischen Bühnenbereich und Repository an. + shows differences between the stage area and the repository. ``$ git diff --word-diff`` - zeigt die geänderten Wörter an. + shows the changed words. ``$ git checkout -- [file]`` - unwiderruflich Änderungen im Arbeitsbereich verwerfen. + irrevocably discard changes in the work area. ``$ git commit -m 'Commit message'`` - einen neuen Commit mit den hinzugefügten Änderungen machen. + make a new commit with the added changes. ``git commit --dry-run --short`` - ``--dry-run`` zeigt, was committet werden würde. - ``--short`` zeigt den Status im Kurzformat an. + ``--dry-run`` + shows what would be committed. + ``--short`` + shows the status in short format. + ``$ git reset [file]`` - zurückkehren zur aktuellen Datei aus dem Bühnenbereich. + return to the current file from the stage area. ``$ git rm [file]`` - entfernen einer Datei aus dem Arbeits- und Bühnenbereich. + remove a file from the work and stage areas. ``$ git stash`` - verschieben der aktuellen Änderungen aus dem Arbeitsbereich in das Versteck - (engl.: stash). + move the current changes from the work area to the stash. ``$ git stash pop`` - übernehmen der Änderungen aus dem Versteck in den Arbeitsbereich und leeren - des Verstecks. + transfer the changes from the hiding place to the work area and empty the + hiding place. ``$ git stash drop`` - leeren eines spezifischen Verstecks. + emptying a specific stash. diff --git a/docs/productive/git/workflows/branches-merge-requests.rst b/docs/productive/git/workflows/branches-merge-requests.rst index 0ffa2f32..39f06edc 100644 --- a/docs/productive/git/workflows/branches-merge-requests.rst +++ b/docs/productive/git/workflows/branches-merge-requests.rst @@ -2,92 +2,83 @@ Branches & merge requests ========================= -Merge requests unterstützen einen Workflow bei regelmäßigen Deployments. +Merge requests support a workflow for regular deployments. -1. Erstellen eines Feature-Branch -================================= +1. Create a feature branch +========================== -Beim Erstellen eines Branches erzeugt ihr eine neue Umgebung, in der ihr -neues ausprobieren könnt. Dies wirkt sich nicht auf den ``master``-Branch -aus. Und ihr könnt euch sicher sein, dass der Branch nicht mit dem ``master`` -zusammengeführt wird, bevor er nicht von einer Person überprüft wurde, mit -der ihr zusammenarbeitet. +When you create a branch, you create a new environment in which to try new +things. This does not affect the ``master`` branch. And you can be sure that the +branch will not be merged with the ``master`` branch until it has been reviewed +by someone you work with. .. note:: - Achtet darauf, dass die Namen der Branches möglichst aussagekräftig sind, - also z.B. ``refactor-user-model`` oder ``user-content-cache``. + Make sure that the names of the branches are as meaningful as possible, e.g. + ``refactor-user-model`` oder ``user-content-cache``. .. note:: - Achtet darauf, dass der ``master``-Branch immer nur Code enthält, der auch - für ein Deployment geeignet ist. + Make sure that the ``master`` branch only contains code that is suitable for + deployment. -2. Hinzufügen von Commits -========================= +2. Adding commits +================= -Sobald ein Feature-Branch erstellt wurde, könnt ihr mit den Änderungen -beginnen. Immer wenn ihr eine Datei hinzufügt, bearbeitet oder löscht, könnt -ihr diese Änderungen in eurem Branch festhalten. Der Fortschritt wird dann in -euren Commits sichtbar. +Once a feature branch has been created, you can start making changes. Whenever +you add, edit or delete a file, you can record these changes in your branch. The +progress will then be visible in your commits. -Die Commits erlauben darüberhinaus auch allen anderen Projektbeteiligten, eure -Arbeit zu verstehen: was ihr getan habt und warum. +The commits also allow everyone else involved in the project to understand your +work: what you’ve done and why. .. note:: - Commit-Messages erleichtern nicht nur das aktuelle Verständnis für eure - Änderungen, sondern erlauben auch später, z.B. mit ``git blame``, - Nachvollziehen zu können, warum ihr diese Änderungen gemacht habt. + Commit messages not only facilitate the current understanding of your + change, but also allow later, for example with ``git blame``, to be able to + understand why you made these changes. -3. Merge request stellen -======================== +3. Submit a merge request +========================= -Merge-Requests initiieren eine Diskussion über ein Bündel von Commits. Da sie -eng in das zugrunde liegenden Git-Repository integriert sind, können alle -Projektbeteiligten genau sehen, welche Änderungen zusammengeführt werden würden, -wenn die Anfrage akzeptiert wird. +Merge requests initiate a discussion about a bundle of commits. Because they are +tightly integrated with the underlying Git repository, everyone involved in the +project can see exactly what changes would be merged if the request is accepted. -Ihr könnt einen Merge-Request auch jederzeit stellen, wenn ihr nicht -weiterkommt und Hilfe oder Rat benötigt. Mit ``@`` in euren Kommentaren könnt -ihr auch bestimmte Personen aus dem Projektteam nach Feedback fragen. +You can also submit a merge request at any time if you get stuck and need help or +advice. With ``@`` in your comments you can also ask certain people from the +project team for feedback. -4. Review und Diskussion des Codes -================================== +4. Review and discussion of the code +==================================== -Nachdem ihr einen Merge Request gestellt habt, wird eine Person oder das -Projektteam Fragen oder Kommentare zu euren Änderungen abgeben: Eventuell -entspricht der Coding Style nicht den Projektrichtlinien, oder des Fehlen -Unit-Tests oder es sieht alles gut aus. Merge Requests sind dazu da, solche -Diskussionen zu fördern und zu dokumentieren. +After you have made a merge request, someone or the project team will submit +questions or comments about your changes: The coding style may not match the +project guidelines, or the lack of unit tests, or everything looks good. Merge +requests are there to promote and document such discussions. -Ihr könnt auch nach einem Merge Request auf diesem Branch ``git push`` -ausführen, z.B. um Fixes, die aus diesen Diskussionen entstanden, ebenfalls -noch in diesen Merge Request aufzunehmen. GitLab zeigt diesen erneuten Commit -in der Ansicht dieses Merge Requests an. +You can also execute ``git push`` on this branch after a merge request, e.g. to +include fixes that arose from these discussions in this merge request. GitLab +shows this new commit in the view of this merge request. .. note:: - Auch die Kommentare zu eurem Merge Request werden in Markdown geschrieben, - sodass ihr auch hier z.B. vorformattierte Textblöcke für Quellcode etc. - verwenden könnt. + The comments on your merge request are also written in Markdown so that you + can use pre-formatted text blocks for source code etc. here too. 5. Deployment ============= -Mit GitLab lassen sich Deployments erstellen z.B. für das automatisierte Testen -oder die Qualitätssicherung in einem Staging-Environment. - -Auf diese Weise lässt sich dann auch sicherstellen, dass die Änderungen deployed -werden können. +GitLab can be used to create deployments, for example for automated testing or +quality assurance in a staging environment. In this way, you can also ensure +that the changes can be deployed. 6. Merge ======== -Wenn auch das Deployment eurer Änderungen erfolgreich war, können eure -Änderungen mit dem ``master``-Branch zusammengeführt werden. +If the deployment of your changes was also successful, your changes can be +merged with the ``master`` branch. .. note:: - Durch das Einfügen bestimmter Schlüsselwörter im Text eures Merge Request - könnt ihr in GitLab Issues mit Code verknüpfen. Wird euer Merge Request - bestätigt, kann z.B. auch ein Issue geschlossen werden. So würde beim - Kommentar ``/close #42`` zu einem Merge Request beim Zusammenführen auch das - Item mit der Nummer 42 geschlossen werden. Weitere Infos hierzu erhaltet ihr unter - `GitLab quick actions - `_. + By inserting certain keywords in the text of your merge request, you can + link issues with code in GitLab. If your merge request is confirmed, an + issue can also be closed, for example. If you comment ``/close #42`` on a + merge request, the item with the number 42 would also be closed when + merging. You can find more information about this under `GitLab quick + actions `_. diff --git a/docs/productive/git/workflows/deploy-branches.rst b/docs/productive/git/workflows/deploy-branches.rst index 9ef5687d..e31871c8 100644 --- a/docs/productive/git/workflows/deploy-branches.rst +++ b/docs/productive/git/workflows/deploy-branches.rst @@ -1,42 +1,40 @@ =============================== -Deployment und Release Branches +Deployment and release branches =============================== -Deployment-Branches +Deployment branches =================== -Sie empfehlen sich, wenn ihr z.B. den Release-Zeitpunkt nicht -selbst bestimmen könnt, beispielsweise wenn eine iOS-Anwendung die -App-Store-Validierung bestehen muss oder euch nur ein festes Zeitfenster für -die Bereitstellung zur Verfügung steht. In diesem Fall empfiehlt sich ein -Production-Branch ``prod``, der den bereitgestellten Code widerspiegelt. Ein -solcher Arbeitsablauf verhindert den zusätzlichen Arbeitsaufwand bei ``git -flow`` beim Releasing, Tagging und Merging. +They are recommended if, for example, you cannot determine the release time +yourself, for example if an iOS application has to pass the app store validation +or you only have a fixed time window available for deployment. In this case, a +production branch ``prod``, that reflects the code provided is recommended. Such +a workflow prevents the additional work of ``git flow`` for releasing, tagging +and merging. -Angenommen, ihr verfügt über eine ``test``-, ``stage``- und ``prod``-Umgebung, -dann wird zunächst ein *Merge Request* für den ``test``-Branch gestellt. Wenn -die Tests bestanden werden, können die Änderungen auch in den ``stage``-Branch -übernommen werden. Wenn die QA beschließt, dass der Code produktionsreif ist, -kann er in den ``master``-Branch übernommen werden. Dieser Vorgang kann sich -mehrfach wiederholen, bis z.B. der Zeitpunkt für das *Going Life* dieser -Änderungen gekommen ist und ein ``prod``-Branch erstellt werden kann. +Assuming you have a ``test``, ``stage`` and ``prod`` environment, a merge +request is first made for the ``test`` branch. If the tests are passed, the +changes can also be adopted in the ``stage`` branch. When the QA decides that +the code is ready for production, it can be transferred to the ``master`` +branch. This process can be repeated several times until, for example, the time +for the going life of these changes has come and a ``prod`` branch can be +created. -Release-Branches +Release branches ================ -Wenn Software an Kunden geliefert werden soll, empfehlen sich Release-Branches. -In diesem Fall sollte jeder Branch eine *Minor Version*, also z.B. ``2.7`` oder -``3.4`` enthalten. Üblicherweise werden diese Branches so spät wie möglich aus -dem ``master``-Branch erzeugt. Dadurch wird bei Bugfixes die Anzahl der Merges, -die auf mehrere Branches verteilt werden müssen, reduziert. Nachdem ein neuer -Release-Branch erstellt wurde, erhält dieser nur noch Bugfixes. Meist werden -diese zunächst in den ``master`` übernommen und anschließend von dort mit -`git cherry-pick `_ in den -Release-Branch übernommen. Dieser *upstream first*-Ansatz wird z.B. von `Google +Release branches are recommended when software is to be delivered to customers. +In this case each branch should contain a minor version, e.g. ``2.7`` or +``3.4``. Usually these branches are created from the ``master`` branch as late +as possible. This reduces the number of merges that have to be distributed +across multiple branches during bug fixes. Usually, these are first transferred +to the ``master`` and then transferred from there to the release branch with +`git cherry-pick `_. This upstream +first approach is e.g. used by `Google `_ -und `Red Hat -`_ -verwendet. Jedes Mal, wenn ein Bugfix in einen Release-Branch übernommen wurde, -wird das Release mit einem `Tag -`_ um eine Patch-Version -angehoben, s.a. `Semantic Versioning `_. +and `Red Hat +`_. +Every time a bug fix has been adopted in a release branch, the release is +increased by a patch version with a `Tag +`_, see also `Semantic +Versioning `_. diff --git a/docs/productive/git/workflows/feature-branches.rst b/docs/productive/git/workflows/feature-branches.rst index 7d605809..79d26bc7 100644 --- a/docs/productive/git/workflows/feature-branches.rst +++ b/docs/productive/git/workflows/feature-branches.rst @@ -1,23 +1,21 @@ ================ -Feature-Branches +Feature branches ================ -`GitHub Flow `_ war als -stark vereinfachte Alternative zu :doc:`git-flow` gedacht, wobei es neben dem -``master``-Branch nur verschiedene Feature-Branches geben sollte. Auch Atlassian -empfiehlt eine `ähnliche Strategie -`_, wobei sie -jedoch ein ``rebase`` der Feature-Branches vornehmen. Diese Strategien bieten -dabei zwei Vorteile: +`GitHub Flow `_ was +intended as a greatly simplified alternative to :doc:`git-flow`, whereby there +should only be different feature branches in addition to the ``master`` branch. +Atlassian also recommends a `similar strategy +`_, but using +``rebase`` for the feature branches. These strategies offer two advantages: -* Das Code-Inventory bleibt relativ klein da die Feature-Branches üblicherweise - schnell in den ``master`` übernommen werden. -* Die Workflows entsprechen den üblichen Methoden von *Continuous Delivery*. +* The code inventory remains relatively small as the feature branches are + usually quickly adopted in the ``master`` branch. +* The workflows correspond to the usual methods of *Continuous Delivery*. -Diese Workflows können jedoch nicht beantworten, wie Deployments in -unterschiedliche Umgebungen oder die Aufteilung in verschiedene Releases -erfolgen können. Möglichkeiten hierfür werden in :doc:`deploy-branches` -beschrieben. +However, these workflows cannot answer how deployments in different environments +or the division into different releases can take place. Options for this are +described in :doc:`deploy-branches`. .. seealso:: * `Feature Driven Development diff --git a/docs/productive/git/workflows/git-flow.rst b/docs/productive/git/workflows/git-flow.rst index 55e84080..998a451b 100644 --- a/docs/productive/git/workflows/git-flow.rst +++ b/docs/productive/git/workflows/git-flow.rst @@ -1,28 +1,28 @@ -=========================== -Git flow und seine Probleme -=========================== +========================= +Git flow and its problems +========================= .. image:: git-flow.png -Git Flow war einer der ersten Vorschläge zur Verwendung von Git-Branches. Es -empfahl einen ``master``-Branch und einen separaten ``develop``-Branch sowie -diverse weitere Branches für Features, Releases und Hotfixes. Die verschiedenen -Entwicklungen sollten im ``develop``-Branch zusammengeführt werden, anschließend -in den ``release``-Branch überführt werden und schließlich im ``master``-Branch -landen. So ist Git Flow zwar ein wohldefinierter, aber komplexer Standard, der -praktisch die folgenden beiden Probleme hat: +Git Flow was one of the earliest suggestions for using Git branches. It +recommended a ``master`` branch and a separate ``develop`` branch as well as +various other branches for features, releases and hotfixes. The various +developments should be brought together in the ``develop`` branch, then +transferred to the ``release`` branch and finally end up in the ``master`` +branch. Git Flow is a well-defined, but complex standard that practically has +the following two problems: -* Die meisten Entwickler und Werkzeuge gehen von der Annahme aus, dass der - ``master``-Branch der Hauptzweig ist von dem aus ``branch`` und ``merge`` - ausgeführt wird. Bei Git Flow entsteht nun zusätzlicher Aufwand da immer - zunächst in den ``develop``-Branch gewechselt werden muss. -* Auch die ``hotfixes``- und ``release``-Branches bringen eine zusätzliche - Komplexität, die nur in den seltensten Fällen Vorteile bringen dürfte. +* Most developers and tools make the assumption that the ``master`` branch is + the main branch from which they run ``branch`` and ``merge``. With Git Flow, + there is now additional effort because you always have to switch to the + ``develop`` branch first. +* The ``hotfixes`` and ``release`` branches also bring additional complexity, + which is only likely to bring advantages in the rarest of cases. -Als Reaktion auf die Probleme von Git Flow entwickelten `GitHub -`_ und `Atlassian -`_ einfachere -Alternativen, die sich meist auf sog. :doc:`feature-branches` beschränken. +In response to the problems of Git Flow, `GitHub +`_ and `Atlassian +`_ developed simpler +alternatives that are mostly limited to so-called :doc:`feature-branches`. .. seealso:: `Vincent Driessen: A successful Git branching model diff --git a/docs/productive/git/workflows/index.rst b/docs/productive/git/workflows/index.rst index f08ac490..b5914134 100644 --- a/docs/productive/git/workflows/index.rst +++ b/docs/productive/git/workflows/index.rst @@ -1,10 +1,10 @@ ============= -Git-Workflows +Git workflows ============= -Die Versionsverwaltung mit git macht das Verzweigen und Zusammenführen -wesentlich einfacher als ältere Versionierungssysteme wie SVN. Dies ermöglicht -eine Vielzahl von Verzweigungsstrategien und Workflows. +Version management with git makes branching and merging much easier than older +versioning systems like SVN. This enables a variety of branching strategies and +workflows. .. toctree:: :hidden: diff --git a/docs/productive/git/workflows/monorepos.rst b/docs/productive/git/workflows/monorepos.rst index d16f32d0..3e3355ba 100644 --- a/docs/productive/git/workflows/monorepos.rst +++ b/docs/productive/git/workflows/monorepos.rst @@ -2,54 +2,51 @@ Monorepos ========= -Git ist ein sehr flexibles Versionskontrollsystem. Insbesondere ``branch`` und -``merge`` sind mächtige Werkzeuge in verteilten Entwicklungsumgebungen. Manchmal -schafft dies jedoch auch eine unnötige Komplexität. In diesen Fällen kann es -sinnvoll sein, mit einem monolithischen Repository oder *Monorepo* zu arbeiten. +Git is a very flexible version control system. In particular, ``branch`` and +``merge`` are powerful tools in distributed development environments. However, +sometimes this also creates unnecessary complexity. In these cases it can make +sense to work with a monolithic repository or monorepo. Definition ========== -* Das Repository enthält mehrere logische Projekte (z.B. einen iOS-Client und - eine Webanwendung) -* Diese Projekte sind meist nur lose miteinander verbunden -* Meist haben diese Projekte auch eine lineare History - -Vor- und Nachteile -================== - -Ein Vorteil von Monorepos kann sein, dass die Aufwände um zu bestimmen, welche -Versionen des einen Projekts mit welchen Versionen des anderen Projekts -kompatibel sind, deutlich verringert sein könnten. Dies ist zumindest immer -dan der Fall, wenn alle Projekte eines Repository von nur einem Entwicklerteam -bearbeitet werden. Dann empfiehlt sich, mit jedem *Merge* wieder eine lauffähige -Version zu erhalten auch wenn die API zwischen den beiden Projekten geändert -wurde. - -Als Nachteil können sich jedoch Performance-Einbußen erweisen. Diese können z.B. -entstehen durch: - -eine große Anzahl an Commits - Da Git DAGs (*directed acyclic graphs*) verwendet um die Historie eines - Projekts darzustellen, werden alle Operationen, die diesen Graphen - durchlaufen, also z.B. ``git log`` oder ``git blame``, langsam werden. - -eine große Anzahl von Refs - Eine große Anzahl von *branches* und *tags* verlangsamen git ebenfalls. - Mit ``git ls-remote`` könnt ihr euch die *Refs* eines Repository anzeigen - lassen und mit ``git gc`` werden lose *Refs* in einer einzigen Datei - zusammengefasst. - - Jede Operation, die den Commit-Verlauf eines Repositories durchlaufen und die - einzelnen *Refs* berücksichtigen muss, wie z.B. bei ``git branch --contains - ``, werden bei einem Repo mit vielen *Refs* langsam. - -eine große Anzahl an versionierten Dateien - Der Index des Directory Cache (``.git/index``) wird von Git verwendet um - zu ermitteln, ob die Datei verändert wurde. Dabei verlangsamen sich mit - zunehmender Anzahl an Dateien viele Vorgänge, wie z.B. ``git status`` - und ``git commit``. - -große Dateien - Große Dateien in einem Teilbaum oder einem Projekt verringern die Leistung - des gesamten Repository. +* The repository contains several logical projects (e.g. an iOS client and a web + application) +* These projects are usually only loosely connected to one another +* Most of these projects also have a linear history + +Pros and cons +============= + +One advantage of monorepos can be that the effort involved in determining which +versions of one project are compatible with which versions of the other project +could be significantly reduced. This is at least always the case when all +projects in a repository are processed by just one development team. Then it is +advisable to get an executable version with each merge, even if the API was +changed between the two projects. + +However, a disadvantage can be a loss of performance. These can arise, for +example, from: + +a large number of commits + Since Git uses DAGs ((*directed acyclic graphs*) to display the history of a + project, all operations that run through this graph, e.g. ``git log`` or + ``git blame``, will be slow. + +a large number of refs + A large number of branches and tags also slow down git. With + ``git ls-remote`` you can display the refs of a repository and with ``git + gc`` loose refs are summarised in a single file. + + Every operation that goes through the commit process of a repository and has + to take the individual refs into account, such as ``git branch --contains + ``, becomes slow with a repo with many refs. + +a large number of versioned files + The directory cache index (``.git/index``) is used by Git to determine + whether the file has been modified. Many processes, such as ``git status`` + and ``git commit``, slow down as the number of files increases. + +large files + Large files in a subtree or project reduce the performance of the entire + repository. diff --git a/docs/productive/git/working-areas.rst b/docs/productive/git/working-areas.rst index 8f30ed6f..55ea8b91 100644 --- a/docs/productive/git/working-areas.rst +++ b/docs/productive/git/working-areas.rst @@ -1,23 +1,21 @@ -Arbeitsbereiche -=============== +Workspaces +========== .. figure:: git-workspaces.png - :alt: Git Arbeitsbereiche + :alt: Git workspaces ``git add`` - fügt Dateien aus dem Arbeitsverzeichnis dem Bühnenbereich (engl.: *staging - area*) hinzu. + adds files from the working directory to the staging area. ``git reset HEAD`` - stellt eine Datei im Arbeitsbereich aus dem Bühnenbereich wieder her. + restores a file in the work area from the stage area. ``git stash`` - verschiebt Dateien aus dem Arbeitsbereich in ein Versteck (engl.: *stash*). + moves files from the workspace to a stash. ``git stash pop`` - holt Dateien aus dem Versteck in den Arbeitsbereich. + brings files from the stash to the work area. ``git push`` - verschiebt Dateien aus dem Bühnenbereich in das Repository. + moves files from the staging area to the repository. ``git push -u origin master`` - ``-u`` legt die Upstream-Referenz für jeden Zweig fest, deren Argumente - anschließend in ``git pull`` o.ä. nicht mehr explizit festgelegt werden - müssen. In unserem Beispiel wird ``master`` im entfernten Repository - referenziert. + ``-u`` defines the upstream reference for each branch, the arguments are + then given and no longer have to be specified explicitly. In our + example ``master`` in the external repository is referenced. diff --git a/docs/productive/index.rst b/docs/productive/index.rst index c7be5288..7fc540ef 100644 --- a/docs/productive/index.rst +++ b/docs/productive/index.rst @@ -1,29 +1,26 @@ -Produkt erstellen -================= - - »Nicht reproduzierbare Einzelereignisse sind für die Wissenschaft ohne - Bedeutung.«[#]_ - -.. [#] Karl Popper in *Logik der Forschung*, 1935 - -Damit auch andere Euren Code nutzen können, sollte er einige Bedingungen -erfüllen: - -* Ihr solltet Euch nicht stillschweigend auf bestimmte Ressourcen und Umgebungen - verlassen -* Erforderliche Software-Pakete und Hardware sollten in den Anforderungen - angegeben werden -* Pfadangaben werden in einem anderen Kontext nur innerhalb Eures Pakets oder in - vorher generierten Verzeichnissen und Dateien funktionieren -* Teilt keine Geheimnisse wie Zugangsdaten oder interne IP-Nummern in Eurem - veröffentlichten Produkt - -Es gibt diverse Werkzeuge, die Euch beim Erstellen von gemeinsam nutzbaren -Produkten unterstützen. Dies können Werkzeuge einerseits für die Versionierung -des :doc:`Quellcodes ` und der :doc:`Trainingsdaten ` -sowie für die Reproduzierbarkeit der :doc:`Ausführungsumgebungen `, -andererseits für das :doc:`testing/index`, :doc:`logging`, :doc:`Dokumentieren -` und :doc:`Erstellen von Paketen ` sein. +Create a product +================ + + «Non-reproducible single occurrences are of no significance to science.»[#]_ + +.. [#] Karl Popper in *The Logic of Scientific Discovery*, 1959 + +In order for others to be able to use your code, it should meet some conditions: + +* You should not silently rely on specific resources and environments +* Required software packages and hardware should be specified in the + requirements +* Path information will only work in a different context within your package or + in previously generated directories and files +* Do not share secrets like login details or internal IP numbers in your + published product + +There are various tools that support you in creating shareable products. These +can be tools on the one hand for the :doc:`versioning of the source code +` and the :doc:`training data ` as well as for the +reproducibility of the :doc:`execution environments `, on the other +hand for :doc:`testing/index`, :doc:`logging`, :doc:`documenting +` and :doc:`creating packages `. .. seealso:: diff --git a/docs/productive/licensing.rst b/docs/productive/licensing.rst index c8b911ad..da536dc5 100644 --- a/docs/productive/licensing.rst +++ b/docs/productive/licensing.rst @@ -1,105 +1,102 @@ -Lizenzieren -=========== +Licensing +========= -Damit andere Eure Software verwenden können, sollte sie eine Lizenz erhalten, -die die Nutzungsbedingungen beschreibt. Andernfalls dürfte sie meist -urheberrechtlich geschützt sein. Urheber sind diejenigen, die zur Software -originär beigetragen haben. Wenn eine Software relizenziert werden soll, ist -die Zustimmung aller Urheber erforderlich. +In order for others to use your software, it should be given a license that +describes the terms of use. Otherwise, it should mostly be protected by +copyright. Authors are those who originally contributed to the software. If +software is to be relicensed, the consent of all authors is required. .. note:: - Dies stellt keine Rechtsberatung dar. Wendet Euch im Zweifelsfall bitte an - einen Anwalt oder die Rechtsabteilung Eures Unternehmens. + This does not constitute legal advice. If in doubt, please contact a lawyer + or the legal department of your company. -Proprietäre Softwarelizenzen ----------------------------- +Proprietary software licenses +----------------------------- -Proprietäre Softwarelizenzen sind selten standardisiert; sie können kommerziell, -Shareware oder Freeware sein. +Proprietary software licenses are rarely standardised; they can be commercial, +shareware, or freeware. -Freie und Open-Source Software-Lizenzen ---------------------------------------- +Free and open source software licenses +-------------------------------------- -Sie werden von der `Free Software Foundation (FSF) -`_ und der `Open Source Initiative -(OSI) `_ definiert. Dabei kann im Wesentlichen -unterschieden werden zwischen Copyleft-, freizügigen- und gemeinfreien Lizenzen. +They are defined by the `Free Software Foundation (FSF) +`_ and the `Open Source Initiative +(OSI) `_. A distinction can essentially be made between +copyleft, permissive and public domain licenses. -Copyleft-Lizenzen +Copyleft licenses ~~~~~~~~~~~~~~~~~ -Copyleft-Lizenzen verpflichten die Lizenznehmer, jegliche Bearbeitung der -Software unter die Lizenz des ursprünglichen Werks zu stellen. Dies soll -Nutzungseinschränkungen der Software verhindern. Die bekannteste Copyleft-Lizenz -ist die GNU General Public License (GPL). Dabei wird das Copyleft der GPL als -sehr stark, das der Mozilla Public License hingegen als sehr schwach angesehen. +Copyleft licenses oblige the licensees to place any processing of the software +under the license of the original work. This is to prevent usage restrictions of +the software. The best known copyleft license is the GNU General Public License +(GPL). The copyleft of the GPL is seen as very strong, while that of the Mozilla +Public License is seen as very weak. -Da die Lizenzgeber nicht selbst an ih eigenes Copyleft gebunden sind, können sie -neue Versionen auch unter proprietärer Lizenz veröffentlichen oder Dritten dies -erlauben (Mehrfachlizenzierung). +Since the licensors are not bound by their own copyleft, they can also publish +new versions under a proprietary license or allow third parties to do so +(multiple licensing). -Durch Copyleft-Lizenzen können jedoch schnell Inkompatibilitäten auch zu freien -Lizenzen ohne Copyleft entstehen. So ist beispielsweise die 3-Clause-BSD-Lizenz -mit der GPL inkompatibel. +Copyleft licenses can quickly lead to incompatibilities with free licenses +without copyleft. For example, the 3 Clause BSD license is incompatible with the +GPL. -Freizügige Open-Source-Lizenzen +Permissive open source licenses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Freizügige oder permissive Open-Source-Lizenzen erlauben eine breitere -Wiederverwendung als die Copyleft-Lizenzen. Ableitungen und Kopien des -Quellcodes können unter Bedingungen verbreitet werden, die grundlegend andere -Eigenschaften haben als die der Originallizenz. Die bekanntesten Beispiele -solcher Lizenzen sind die MIT-Lizenz und die BSD-Lizenz. +Permissive open source licenses allow broader reuse than copyleft licenses. +Derivatives and copies of the source code can be distributed under conditions +that have fundamentally different properties than those of the original license. +The best known examples of such licenses are the MIT license and the BSD +license. -Gemeinfreie Lizenzen -~~~~~~~~~~~~~~~~~~~~ +Public domain licenses +~~~~~~~~~~~~~~~~~~~~~~ -Bei gemeinfreien oder Public Domain-Lizenzen gehen die Urheberrechte an die -Allgemeinheit über. Zur Kennzeichnung der Freigabe weitest möglicher -Nutzungsrechte wurde die Creative Commons Zero-Lizenz erstellt. +In the case of public domain licenses, copyrights are transferred to the general +public. The Creative Commons Zero license was created to identify the release of +the greatest possible usage rights. -Auswahl einer geeigneten Lizenz -------------------------------- +Choosing a suitable license +--------------------------- -Übersichten über mögliche Lizenzen findet Ihr in `SPDX License List -`_ oder `OSI Open Source Licenses by Category -`_. Bei der Wahl einer geeigneten -Lizenz unterstützt Euch die Website `Choose an open source license -`_. +Overviews of possible licenses can be found in the `SPDX License List +`_ or `OSI Open Source Licenses by Category +`_. The website `Choose an open source +license `_ supports you in choosing a suitable +license. GitHub ------ -Auf `GitHub `_ könnt Ihr Euch eine Open Source-Lizenz in -Eurem Repository erstellen lassen. - -#. Geht zur Hauptseite Eures Repository. -#. Klickt auf *Create new file* und gebt anschließend als Dateiname ``LICENSE`` - oder ``LICENSE.md`` ein. -#. Anschließend könnt Ihr rechts neben dem Feld für den Dateinamen auf *Choose a - license template* klicken. -#. Nun könnt Ihr die für Euer Repository passende Open Source-Lizenz auswählen. -#. Ihr werdet nun zu zusätzlichen Angaben aufgefordert, sofern die gewählte - Lizenz dies erfordert. -#. Nachdem Ihr eine Commit-Message angegeben habt, z.B. ``Add license``, könnt - Ihr auf *Commit new file* klicken. - -Falls Ihr in Eurem Repository bereits eine ``/LICENSE``-Datei hinzugefügt habt, -verwendet GitHub `licensee `_ um die Datei -mit einer kurzen `Liste von Open-Source-Lizenzen -`_ abzugleichen. Falls GitHub die Lizenz -Eures Repository nicht erkennen kann, enthält es möglicherweise mehrere -Lizenzen oder ist zu komplex. Überlegt Euch dann, ob Ihr die Lizenz vereinfachen -könnt, z.B. indem Ihr Komplexität in die ``/README``-Datei auslagert. - -Umgekehrt könnt Ihr auf GitHub auch nach Repositories mit bestimmten Lizenzen -oder Lizenzfamilien suchen. Eine Übersicht über die Lizenz-Schlüsswlwörter -erhaltet Ihr in `Searching GitHub by license type +On `GitHub `_ you can have an open source license created in +your repository. + +#. Go to the main page of your repository. +#. Click on *Create new file* and then enter ``LICENSE`` or ``LICENSE.md``as the + file name. +#. Then you can click on *Choose a license template*. +#. Now you can select the open source license that is suitable for your + repository. +#. You will now be asked for additional information if the selected license + requires this. +#. After you have given a commit message, for example ``Add license``, you can + click on *Commit new file*. + +If you’ve already added a ``/LICENSE`` file to your repository, GitHub uses +`licensee `_ to compare the file with a +short `list of open source licenses `_. +If GitHub can’t detect your repository’s license, it might contain multiple +licenses or be too complex. Then consider whether you can simplify the license, +for example by outsourcing complexity to the ``/README`` file. + +Conversely, you can also search for repositories with specific licenses or +license families on GitHub. You can get an overview of the license keywords in +`Searching GitHub by license type `_. -Schließlich könnt Ihr Euch von `Shields.io `_ ein -License-Badge generieren lassen, das Ihr z.B. auf Eurer ``README``-Datei -einbinden könnt, z.B. +Finally, you can have `Shields.io `_ generate a license +badge for you, which you can include in your ``README`` file, for example .. code-block:: rst @@ -113,31 +110,31 @@ einbinden könnt, z.B. .. |License| image:: https://img.shields.io/github/license/veit/jupyter-tutorial.svg :target: https://github.com/veit/jupyter-tutorial/blob/master/LICENSE -Standardformat für die Lizenzierung ------------------------------------ +Standard format for licensing +----------------------------- -Wir empfehlen die Verwendung von ``SPDX-FileCopyrightText: [year] [copyright -holder]``. Üblicherweise sollte die Angabe das gesamte Software-Produkt -umfassen, Ihr könnt jedoch auch Elemente ausnehmen. +We recommend using ``SPDX-FileCopyrightText: [year] [copyright holder]``. +Usually the information should include the entire software product, but you can +also exclude elements. -Konformität überprüfen ----------------------- +Check conformity +---------------- -`REUSE `_ wurde von der Free Software Foundation -Europe (FSFE) initiiert, um die Lizenzierung freier Software-Projekte zu -erleichtern. Das `REUSE tool `_ überprüft -Lizenzen und unterstützt Euch bei der Einhaltung der Lizenzkonformität. -Mit der `REUSE API `_ könnt Ihr Euch auch -ein dynamisches Compliance-Badge generieren: +`REUSE `_ was initiated by the Free Software Foundation +Europe (FSFE) to facilitate the licensing of free software projects. The `REUSE +tool `_ checks licenses and supports you in +compliance with the license. With the `REUSE API +`_ you can also generate a dynamic compliance +badge: .. figure:: reuse-compliant.png :alt: REUSE-compliant Badge -CI-Workflow +CIR wrkflow ~~~~~~~~~~~ -Ihr könnt REUSE einfach in Euren Continuous Integration-Workflow integrieren, -z.B. für GitLab in der ``.gitlab-ci.yml``-Datei mit: +You can easily integrate REUSE into your continuous integration workflow, e.g. +for GitLab in the ``.gitlab-ci.yml`` file with: .. code-block:: yaml @@ -148,22 +145,22 @@ z.B. für GitLab in der ``.gitlab-ci.yml``-Datei mit: script: - reuse lint -Alternativen +Alternatives ~~~~~~~~~~~~ `SPDX `_ - SPDX definiert eine standardisierte Methode zum Austausch von Urheberrechts- - und Lizenzinformationen zwischen Projekten und Personen + SPDX defines a standardised method for exchanging copyright and license + information between projects and people `ClearlyDefined `_ - Es sammelt und zeigt Informationen über die Lizenzierungs- und - Urheberrechtssituation eines Software-Projekts an + It collects and displays information about the licensing and copyright + situation of a software project `OpenChain `_ - Es empfiehlt REUSE als eine Komponente, um die Klarheit der Lizenz- und - Urheberrechtssituation zu verbessern, stellt jedoch höhere Anforderungen, um - eine vollständige Konformität zu erreichen. + It recommends REUSE as a component to improve the clarity of the licensing + and copyright situation, but has more stringent requirements to achieve full + compliance. `FOSSology `_ - Toolkit für die Einhaltung freier Software, das Informationen in einer - Datenbank mit Lizenz-, Copyright- und Exportscanner + Free software compliance toolkit that stores information in a database with + license, copyright, and export scanners .. seealso:: * `A Quick Guide to Software Licensing for the Scientist-Programmer diff --git a/docs/productive/logging.ipynb b/docs/productive/logging.ipynb index 830428c6..669ff28e 100644 --- a/docs/productive/logging.ipynb +++ b/docs/productive/logging.ipynb @@ -4,28 +4,28 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Loggen\n", + "# Logging\n", "\n", - "Das [logging](https://docs.python.org/3/library/logging.html#module-logging)-Modul ist Teil der Python-Standardbibliothek. Es ist beschrieben in [PEP 0282](https://www.python.org/dev/peps/pep-0282). Eine erste Einführung in das Modul erhaltet ihr in [Basic Logging Tutorial](https://docs.python.org/3/howto/logging.html#logging-basic-tutorial).\n", + "The [logging](https://docs.python.org/3/library/logging.html#module-logging) module is part of the Python standard library. It is described in [PEP 0282](https://www.python.org/dev/peps/pep-0282). You can get a first introduction to the module in the [Basic Logging Tutorial](https://docs.python.org/3/howto/logging.html#logging-basic-tutorial).\n", "\n", - "Alternativ könnt ihr auch [loguru](https://github.com/Delgan/loguru) verwenden, das Logging fast so einfach wie `print`-Anweisungen macht.\n", + "Alternatively, you can also use [loguru](https://github.com/Delgan/loguru), which makes logging almost as easy as using `print` instructions.\n", "\n", - "Logging erfüllt üblicherweise zwei verschiedene Zwecke:\n", + "Logging usually serves two different purposes:\n", "\n", - "**Diagnose:**\n", + "**Diagnosis:**\n", "\n", - "* Ihr könnt euch den Kontext von bestimmten Ereignissen anzeigen lassen.\n", - "* Tools wie [Sentry](https://sentry.io/) gruppieren zusammengehörende Ereignisse und erleichtern die Benutzeridentifikation etc., sodass Entwickler die Fehlerursache schneller finden können.\n", + "* You can display the context of certain events.\n", + "* Tools like [Sentry](https://sentry.io/) group related events and facilitate user identification, etc., so that developers can find the cause of the error more quickly.\n", "\n", "**Monitoring:** \n", "\n", - "* Das Logging zeichnet Ereignisse für benutzerdefinierten Heuristiken auf, z.B. für Geschäftsanalysen. Diese Aufzeichnungen können für Berichte oder Optimierungen der Geschäftsziele verwendet und ggf. visualisiert werden.\n", + "* The logging records events for user-defined heuristics, e.g. for business analyses. These records can be used for reports or optimisation of the business goals and, if necessary, visualised.\n", "\n", - "Welche Vorteile bietet `logging` nun gegenüber `print`?\n", + "What are the advantages of `logging` over `print`?\n", "\n", - "* Die Logdatei enthält alle verfügbaren Diagnoseinformationen wie Dateiname, Pfad, Funktion und Zeilennummer\n", - "* Alle Ereignisse sind über den Root-Logger automatisch verfügbar, sofern Sie sie nicht explizit herausgefiltert werden.\n", - "* Logging kann wahlweise durch eine der folgenden beiden Methoden stummgeschaltet werden: [logging.Logger.setLevel()](https://docs.python.org/3/library/logging.html#logging.Logger.setLevel) oder [logging.disabled](https://docs.python.org/3/library/logging.html#logging.disable)." + "* The log file contains all available diagnostic information such as file name, path, function and line number.\n", + "* All events are automatically available via the root logger unless they are explicitly filtered out.\n", + "* Logging can be muted using either of the following two methods: [logging.Logger.setLevel()](https://docs.python.org/3/library/logging.html#logging.Logger.setLevel) or [logging.disabled](https://docs.python.org/3/library/logging.html#logging.disable)." ] }, { @@ -41,9 +41,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispielkonfiguration über eine INI-Datei\n", + "## Example configuration via an INI file\n", "\n", - "Im folgenden Beispiel wird die Datei `development.ini` in diesem Verzeichnis geladen:\n", + "The following example loads the file `development.ini` in this directory:\n", "\n", "```ini\n", "[loggers]\n", @@ -105,19 +105,19 @@ "source": [ "**Pro:**\n", "\n", - "* Möglichkeit, die Konfiguration während des Betriebs zu aktualisieren, indem die Funktion `logging.config.listen()` verwendet wird um an einem Socket zu lauschen.\n", - "* In verschiedenen Umgebungen können unterschiedliche Konfigurationen verwendet werden, also z.B. kann in der `development.ini` `DEBUG` als Log-Level angegeben werden, während in der `production.ini` `WARN` verwendet wird.\n", + "* Possibility to update the configuration on the fly by using the function `logging.config.listen()` to listen on a socket.\n", + "* Different configurations can be used in different environments, for example in `development.ini` the log level can be specified as `DEBUG` while the log level in `production.ini` used `WARN`.\n", "\n", "**Con:**\n", "\n", - "* Weniger Kontrolle z.B. gegenüber benutzerdefinierten Filtern oder Logger, die im Code konfiguriert sind." + "* Less control, for example, compared to user-defined filters or loggers that are configured in the code." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispielkonfiguration über ein Dictionary" + "## Example for a configuration via a dictionary" ] }, { @@ -155,18 +155,18 @@ "source": [ "**Pro:**\n", "\n", - "* Aktualisieren während des Betriebs\n", + "* Update during operation\n", "\n", "**Con:**\n", "\n", - "* Weniger Kontrolle als beim Konfigurieren eines Loggers im Code" + "* Less control than when configuring a logger in code" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispielkonfiguration direkt im Code" + "## Example configuration directly in the code" ] }, { @@ -188,41 +188,41 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ könnt ihr auch *Magic Commands* verwenden:\n", + "Alternatively, you can also use *Magic Commands*:\n", "\n", "| Befehl | Beschreibung |\n", "| -------------- | ----------------------------------------------------------------------------------------- |\n", - "| `%logstart` | Startet das Logging irgendwo in einer Session |\n", + "| `%logstart` | Starts logging anywhere in a session |\n", "| | `%logstart [-o\\|-r\\|-t\\|-q] [log_name [log_mode]]` |\n", - "| | Wenn kein Name angegeben wird, wird `ipython_log.py` im aktuellen Verzeichnis verwendet. |\n", - "| | `log_mode` ist ein optionaler Parameter. Folgende Modi können angegeben werden: |\n", - "| | * `append` hängt die Logging-Informationen am Ende einer vorhandenen Datei an |\n", - "| | * `backup` benennt die vorhandene Datei um in `name~` und schreibt in `name` |\n", - "| | * `global` hängt die Logging-Informationen am Ende einer vorhandenen Datei im |\n", - "| | * `over` überschreibt eine existierende Log-Datei |\n", - "| | * `rotate` erstellt rotierende Log-Dateien: `name.1~`, `name.2~`, etc. |\n", - "| | Optionen: |\n", - "| | * `-o` logt auch den Output von IPython |\n", - "| | * `-r` logt *raw* Output |\n", - "| | * `-t` schreibt einen Zeitstempel vor jeden Logeintrag |\n", - "| | * `-q` unterdrückt die Logging-Ausgabe |\n", - "| `%logon` | Neustart des Logging |\n", - "| `%logoff` | Temporäres Beenden des Logging |\n", + "| | If no name is given, `ipython_log.py` is used in the current directory. |\n", + "| | `log_mode` is an optional parameter. The following modes can be specified: |\n", + "| | – `append` appends the logging information to the end of an existing file |\n", + "| | – `backup` renames the existing file to `name~` and writes to `name` |\n", + "| | – `global` appends the logging information at the end of an existing file |\n", + "| | – `over` overwrites an existing log file |\n", + "| | – `rotate` creates rotating log files: `name.1~`, `name.2~`, etc. |\n", + "| | Options: |\n", + "| | – `-o` also logs the output of IPython |\n", + "| | – `-r` logs raw output |\n", + "| | – `-t` writes a time stamp in front of each log entry |\n", + "| | – `-q` suppresses the logging output |\n", + "| `%logon` | Restart the logging |\n", + "| `%logoff` | Temporary termination of logging |\n", "\n", "**Pro:**\n", "\n", - "* Vollständige Kontrolle über die Konfiguration\n", + "* Complete control over the configuration\n", "\n", "**Con:**\n", "\n", - "* Änderungen in der Konfiguration erfordern eine Änderung des Quellcodes" + "* Changes in the configuration require a change in the source code" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "> **Siehe auch:**\n", + "> **See also:**\n", "> \n", "> * [logging configuration](https://docs.python.org/3/howto/logging.html#configuring-logging)\n" ] diff --git a/docs/productive/packaging/binary-extensions.rst b/docs/productive/packaging/binary-extensions.rst index 90980bc7..768794a7 100644 --- a/docs/productive/packaging/binary-extensions.rst +++ b/docs/productive/packaging/binary-extensions.rst @@ -1,282 +1,265 @@ Binary Extensions ================= -Eine der Funktionen des CPython-Interpreters besteht darin, dass neben der -Ausführung von Python-Code auch eine reichhaltige C-API für die Verwendung -durch andere Software verfügbar ist. Eine der häufigsten Anwendungen dieser -C-API besteht darin, importierbare C-Erweiterungen zu erstellen, die Dinge -ermöglichen, die im reinen Python-Code nur schwer zu erreichen sind. +One of the features of the CPython interpreter is that in addition to executing +Python code, it also has a rich C API available for use by other software. One +of the most common uses of this C API is to create importable C extensions that +allow things that are difficult to achieve in pure Python code. Use Cases --------- -Die typischen Anwendungsfälle für Binary Extensions lassen sich in drei -Kategorien unterteilen: - -Accelerator-Module - Diese Module sind eigenständig und werden nur erstellt, um schneller zu - laufen als der entsprechende reine Python-Code. Im Idealfall haben die - Beschleunigermodule immer ein Python-Äquivalent, das als Fallback verwendet - werden kann, wenn die beschleunigte Version auf einem bestimmten System - nicht verfügbar ist. - - Die CPython-Standardbibliothek verwendet viele Beschleunigermodule. - -Wrapper-Module - Diese Module werden erstellt, um vorhandene C-Interfaces in Python verfügbar - zu machen. Sie können entweder die zugrunde liegenden C-Interfaces direkt - verfügbar oder eine *Pythonic*-API bereitgestellt werden, die - Features von Python verwendet, um die API einfacher zu verwenden. - - Die CPython-Standardbibliothek verwendet umfangreiche Wrapper-Module. - -Systemzugriffe auf niedriger Ebene - Diese Module werden erstellt, um auf Funktionen der - CPython-Laufzeitumgebung, des Betriebssystems oder der - zugrundeliegenden Hardware zuzugreifen. Durch plattformspezifischen Code - können mit solchen Erweiterungsmodulen Dinge erreicht werden, die mit reinem - Python-Code nicht möglich wären. - - Eine Reihe von CPython-Standard-Bibliotheksmodulen sind in C geschrieben, um - auf Interpreter-Interna zuzugreifen, die nicht auf der Sprachebene verfügbar - sind. - - Eine besonders bemerkenswerte Eigenschaft von C-Erweiterungen ist, dass sie, - den Global Interpreter Lock (GIL) von CPython bei lang andauernden - Operationen freigeben können, unabhängig davon, ob diese Operationen CPU- - oder IO-gebunden sind. - -Nicht alle Erweiterungsmodule passen genau in die oben genannten Kategorien. So -umfassen z.B. die in `NumPy `_ enthaltenen -Erweiterungsmodule alle drei Anwendungsfälle: - -* Sie verschieben innere Schleifen aus Geschwindigkeitsgründen auf C, -* umschließen externe Bibliotheken in C, FORTRAN und anderen Sprachen und -* verwenden Systemschnittstellen auf niedriger Ebene für CPython und das - zugrunde liegende Betriebssystem, um die gleichzeitige Ausführung von - vektorisierten Operationen zu unterstützen und das Speicherlayout von - erstellten Objekten genau zu steuern. - -Nachteile ---------- +The typical use cases for binary extensions can be divided into three +categories: + +Accelerator modules + These modules are stand-alone and are only created to run faster than the + corresponding pure Python code. Ideally, the accelerator modules always + have a Python equivalent that can be used as a fallback if the accelerated + version is not available on a particular system. + + The CPython standard library uses many accelerator modules. + +Wrapper modules + These modules are created to make existing C interfaces available in Python. + You can either make the underlying C interfaces directly available or + provide a *Pythonic* API that uses features of Python to make the API easier + to use. + + The CPython standard library uses extensive wrapper modules. + +Low-level system access + These modules are created to access functions of the CPython runtime + environment, the operating system or the underlying hardware. With + platform-specific code, things can be achieved that would not be possible + with pure Python code. + + A number of CPython standard library modules are written in C to access + interpreter internals that are not available at the language level. + + A particularly noteworthy property of C extensions is that they can release + the Global Interpreter Lock (GIL) of CPython for long-running operations, + regardless of whether these operations are CPU or IO-bound. -Früher war der Hauptnachteil bei der Verwendung von Binary Extensions, dass -dadurch die Distribution der Software erschwert wurde. Heute ist dieser Nachteil -durch :term:`wheel` kaum noch vorhanden. Einige Nachteile bleiben dennoch: +Not all expansion modules fit exactly into the above categories. For example, +the extension modules contained in `NumPy `_ cover all +three use cases: -* Die Installation aus den Sourcen bleibt weiterhin kompliziert. -* Ggf. gibt es kein passendes :term:`wheel` für den verwendeten Build des - CPython-Interpreters oder alternativen Interpretern wie `PyPy - `_, `IronPython `_ oder `Jython +* They move inner loops to C for speed reasons, +* wrap external libraries in C, FORTRAN and other languages and +* use low-level system interfaces of CPython and the underlying operating system + to support the concurrent execution of vectorised operations and to precisely + control the memory layout of objects created. + +Disadvantages +------------- + +In the past, the main disadvantage of using binary extensions was that they made +it difficult to distribute the software. Today this disadvantage due to +:term:`wheel` is hardly present. However, some disadvantages remain: + +* The installation from the sources remains complicated. +* Possibly there is no suitable :term:`wheel` for the build of the CPython + interpreter or alternative interpreters such as `PyPy + `_, `IronPython `_ or `Jython `_. -* Die Wartung und Pflege der Pakete ist aufwändiger da die Maintainer nicht nur - mit Python sondern auch mit einer anderen Sprache und der CPython C-API - vertraut sein müssen. Zudem erhöht sich die Komplexität, wenn neben der - Binary Extension auch eine Python-Fallback-Implementierung bereitgestellt - wird. -* Schließlich funktionieren häufig auch Importmechanismen, wie der direkte - Import aus ZIP-Dateien, nicht für Extensions-Module. - -Alternativen +* The maintenance of the packages is more time-consuming because the maintainers + not only have to be familiar with Python but also with another language and + the CPython C API. In addition, the complexity increases if a Python fallback + implementation is provided in addition to the binary extension. +* Finally, import mechanisms, such as direct import from ZIP files, often do not + work for extension modules. + +Alternatives ------------ -… zu Accelerator-Modulen +… to accelerator modules ~~~~~~~~~~~~~~~~~~~~~~~~ -Wenn Extensions-Module nur verwendet werden, um Code schneller auszuführen, -sollten auch eine Reihe anderer Alternativen in Betracht gezogen werden: - -* Sucht nach vorhandenen optimierten Alternativen. Die CPython-Standardbibliothek - enthält eine Reihe optimierter Datenstrukturen und Algorithmen, insbesondere in - den builtins und den Modulen ``collections`` und ``itertools``. - - Gelegentlich bietet auch der :term:`Python Package Index (PyPI)` zusätzliche - Alternativen. Manchmal kann ein Modul eines Drittanbieters die Notwendigkeit - vermeiden, ein eigenes Accelerator-Modul zu erstellen. - -* Für lange laufende Anwendungen kann der JIT-kompilierte `PyPy - `_-Interpreter eine geeignete Alternative zum - Standard-CPython sein. Die Hauptschwierigkeit bei der Übernahme von PyPy - besteht typischerweise in der Abhängigkeit von anderen Binary - Extensions-Modulen. Während PyPy die CPython C API emuliert, verursachen - Module, die darauf angewiesen sind, Probleme für das PyPy JIT, und die - Emulation legt oft Defekte in Extensions-Modulen offen, die CPython - toleriert. (häufig bei Reference Counting Errors). - -* `Cython `_ ist ein ausgereifter statischer Compiler, der - den meisten Python-Code zu C-Extensions-Modulen kompilieren kann. Die - anfängliche Kompilierung bietet einige Geschwindigkeitssteigerungen (durch - Umgehung der CPython-Interpreter-Ebene), und Cythons optionale statische - Typisierungsfunktionen können zusätzliche Möglichkeiten für - Geschwindigkeitssteigerungen bieten. Für Python-Programmierer bietet Cython - eine niedrigere Eintrittshürde relativ zu anderen Sprachen wie C oder C ++). - - Die Verwendung von Cython hat jedoch den Nachteil, die Komplexität der - Verteilung der resultierenden Anwendung zu erhöhen. - -* `Numba `_ ist ein neueres Tool, das die `LLVM - Compiler-Infrastruktur `_ nutzt, um während der Laufzeit - selektiv Teile einer Python-Anwendung auf nativen Maschinencode zu - kompilieren. Es erfordert, dass LLVM auf dem System verfügbar ist, auf dem der - Code ausgeführt wird. Es kann, insbesondere bei vektorisierbaren Vorgängen - zu erheblichen Geschwindigkeitssteigerungen führen. - -… zu Wrapper-Modulen +If extensions modules are only used to make code run faster, a number of other +alternatives should also be considered: + +* Looks for existing optimised alternatives. The CPython standard library + contains a number of optimised data structures and algorithms, especially in + the builtins and the modules ``collections`` and ``itertools``. + + Occasionally the :term:`Python Package Index (PyPI)` also offers additional + alternatives. Sometimes a third-party module can avoid the need to create your + own accelerator module. + +* For long-running applications, the JIT-compiled `PyPy + `_ interpreter can be a suitable alternative to the + standard CPython. The main difficulty with adopting PyPy is typically the + dependence on other Binary Extensions modules. While PyPy emulates the + CPython C API, modules that rely on it cause problems for the PyPy JIT, and + the emulation often exposes defects in extension modules that CPython + tolerates. (often with reference counting errors). + +* `Cython `_ is a sophisticated static compiler that can + compile most Python code into C-Extension modules. The initial compilation + offers some speed increases (by bypassing the CPython interpreter level), and + Cython’s optional static typing functions can provide additional speed + increases. For Python programmers, Cython offers a lower barrier to entry + relative to other languages such as C or C ++). + + However, using Cython has the disadvantage of adding complexity to the + distribution of the resulting application. + +* `Numba `_ is a newer tool that uses the `LLVM + compiler infrastructure `_ to selectively compile parts of + a Python application to native machine code at runtime. It requires LLVM to be + available on the system the code is running on. It can lead to considerable + increases in speed, especially with vectorisable processes. + +… to wrapper modules ~~~~~~~~~~~~~~~~~~~~ -Die C-ABI (`Application Binary Interface -`_) ist ein Standard für -die gemeinsame Nutzung von Funktionen zwischen mehreren Anwendungen. Eine der -Stärken der CPython C-API (`Application Programming Interface -`_) ist es, dass -Python-Benutzer diese Funktionalität nutzen können. Das manuelle Wrapping von -Modulen ist jedoch sehr mühsam, so dass eine Reihe anderer Alternativen in -Betracht gezogen werden sollten. - -Die unten beschriebenen Ansätze vereinfachen nicht die Distribution, aber sie -können den Wartungsaufwand im Vergleich zu Wrapper-Modulen deutlich reduzieren. - -* `Cython `_ eignet sich nicht nur zum Erstellen von - Accelerator-Modulen, sondern auch zum Erstellen von Wrapper-Modulen. Da das - Wrapping der API immer noch von Hand erfolgen muss, ist es keine gute Wahl beim - Wrapping großer APIs. - -* `cffi `_ ist das Projekt einiger `PyPy - `_-Entwickler, um Entwicklern, die sowohl Python als auch C - bereits kennen, die Möglichkeit zu geben, ihre C-Module für Python-Anwendungen - verfügbar zu machen. Es macht das Wrapping eines C-Moduls basierend auf seinen - Header-Dateien relativ einfach, auch wenn man sich mit C selbst nicht auskennt. - - Einer der Hauptvorteile von cffi besteht darin, dass es mit dem PyPy-JIT - kompatibel ist, sodass CFFI-Wrapper-Module vollständig von den - PyPy-Tracing-JIT-Optimierungen partizipieren können. - -* `SWIG `_ ist ein Wrapper Interface Generator, der eine - Vielzahl von Programmiersprachen, einschließlich Python, mit C- und C++-Code - verbindet. - -* Das ``ctypes``-Modul der Standardbibliothek ist zwar nützlich um Zugriff auf - C-Schnittstellen zu erhalten, wenn die Header-Informationen jedoch nicht - verfügbar sind, es leidet jedoch daran, dass es nur auf der C ABI-Ebene - arbeitet und somit keine automatische Konsistenzprüfung zwischen der - exportierten Schnittstelle und dem Python-Code macht. Im Gegensatz dazu - können die obigen Alternativen alle auf der C-API arbeiten und - C-Header-Dateien verwenden, um die Konsistenz zu gewährleisten. - -… für den Systemzugriff auf niedriger Ebene -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Für Anwendungen, die Low Level System Access benötigen, ist eine Binary -Extension oft ist der beste Weg. Dies gilt insbesondere für den Low Level Access -auf die CPython-Runtime, da einige Operationen (wie das Freigeben des Global -Interpreter Lock (GIL) nicht zulässig sind, wenn der Interpreter den Code -selbst ausführt, gerade auch wenn Module wie ``ctypes`` oder ``cffi`` verwendet -werden, um Zugriff auf das relevanten C-API-Interfaces zu erhalten. - -In Fällen, in denen das Erweiterungsmodul das zugrunde liegende Betriebssystem -oder die Hardware (statt der CPython-Runtime) manipuliert, ist es manchmal -besser, eine normale C-Bibliothek (oder eine Bibliothek in einer anderen -Programmiersprache wie C ++ oder Rust) zu schreiben, die eine C-kompatible ABI), -bereitstellt und anschließend eine der oben beschriebenen Wrapping-Techniken zu -verwenden um das Interface als importierbares Python-Modul verfügbar zu machen. - -Implementierung ---------------- - -Der `CPython Extending and Embedding guide -`_ enthält eine Einführung in das -Schreiben eigener Extension-Module in C: `Extending Python with C or C++ -`_. Beachtet jedoch bitte, -dass diese Einführung nur die grundlegenden Tools zum Erstellen von -Erweiterungen beshreibt, die im Rahmen von CPython bereitgestellt werden. -Third-Party-Tools wie `Cython `_, `cffi -`_, `SWIG `_ und `Numba -`_ bieten sowohl einfachere als auch ausgeklügeltere -Ansätze zum Erstellen von C- und C ++ - Erweiterungen für Python. +The C-ABI (`Application Binary Interface +`_) is a standard +for the common use of functions between several applications. One of the +strengths of the CPython C-API (`Application Programming Interface +`_) is that Python users can take advantage +of this functionality. However, manually wrapping modules is very tedious, so a +number of other alternatives should be considered. + +The approaches described below do not simplify distribution, but they can +significantly reduce the maintenance effort compared to wrapper modules. + +* `Cython `_ is useful not only for creating accelerator + modules, but also for creating wrapper modules. Since the API still needs to + be wrapped by hand, it is not a good choice when wrapping large APIs. + +* `cffi `_ is the project of some `PyPy + `_ developers to give developers who already know both + Python and C the possibility to make their C modules available for Python + applications. It makes wrapping a C module based on its header files + relatively easy, even if you are not familiar with C itself. + + One of the main advantages of cffi is that it is compatible with the PyPy JIT + so that CFFI wrapper modules can fully participate in the PyPy tracing JIT + optimisations. + +* `SWIG `_ is a wrapper interface generator that combines + a variety of programming languages, including Python, with C and C ++ code. + +* The ``ctypes`` module of the standard library is useful to get access to C + interfaces, but if the header information is not available, it suffers from + the fact that it only works on the C ABI level and therefore no automatic + consistency check between the exported Interface and the Python code. In + contrast, the alternatives above can all work on the C API and use C header + files to ensure consistency. + +… for low-level system access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For applications that require low level system access, a binary extension is +often the best option. This applies in particular to the low level access to the +CPython runtime, since some operations (such as releasing the Global Interpreter +Lock (GIL) are not permitted when the interpreter executes the code itself, +especially when modules such as ``ctypes`` or ``cffi`` are used to Get access to +the relevant C-API interfaces. + +In cases where the expansion module is manipulating the underlying operating +system or hardware (instead of the CPython runtime), it is sometimes better to +write a normal C library (or a library in another programming language such as +C++ or Rust) that provides a C-compatible ABI) and then use one of the wrapping +techniques described above to make the interface available as an importable +Python module. + +Implementation +-------------- + +The `CPython Extending and Embedding guide +`_ provides an introduction to writing +your own extension modules in C: `Extending Python with C or C++ +`_. RPlease note, however, +that this tutorial only covers the basic extension building tools provided with +CPython. Third-party tools like `Cython `_, `cffi +`_, `SWIG `_ and `Numba +`_ offer both simpler and more sophisticated +approaches to creating C and C ++ extensions for Python. .. seealso:: `Python Packaging User Guide: Binary Extensions `_ - behandelt nicht nur verschiedene verfügbare Tools, die die Erstellung von - Binary Extensions vereinfachen, sondern erläutert auch die verschiedenen - Gründe, warum das Erstellen eines Extension Module wünschenswert sein - könnte. + not only covers various tools available to make creating Binary Extensions + easier, but it also explains the various reasons why it might be desirable + to create an Extension Module. -Erstellen von Binary Extensions -------------------------------- +Creating binary extensions +-------------------------- -Binary Extensions für Windows +Binary extensions for Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Bevor ihr eine Binary Extension erstellen könnt, müsst ihr sicherstellen, dass -ihr einen geeigneten Compiler zur Verfügung habt. Unter Windows wird Visual C -zum Erstellen des offiziellen CPython-Interpreters verwendet und er sollte auch -zum Erstellen kompatibler Binary Extensions verwendet werden: +Before you can create a binary extension, you have to make sure that you have a +suitable compiler available. On Windows, Visual C is used to create the official +CPython interpreter, and it should also be used to create compatible binary +extensions: -für Python 2.7 - #. installiert `Microsoft Visual C++ Compiler for Python 2.7 +for Python 2.7 + #. install `Microsoft Visual C++ Compiler for Python 2.7 `_ - #. aktualisiert :term:`pip` und :term:`setuptools` -für Python 3.4 - #. installiert `Microsoft Windows SDK for Windows 7 and .NET Framework 4 + #. update :term:`pip` and :term:`setuptools` +for Python 3.4 + #. install `Microsoft Windows SDK for Windows 7 and .NET Framework 4 `_ - #. arbeitet mit dem SDK-Command-Prompt (mit den Umgebungsvariablen und dem - SDK in ``PATH``). - #. setzt ``DISTUTILS_USE_SDK=1``. -für Python 3.5+ - #. installiert `Visual Studio Code `_ mit + #. work with the SDK command prompt (with the environment variables and the + SDK in ``PATH``). + #. set ``DISTUTILS_USE_SDK=1``. +for Python 3.5+ + #. install `Visual Studio Code `_ with `Python Extension `_ .. note:: - Visual Studio arbeitet ab Python 3.5 abwärtskompatibel, d.h., dass jede - zukünftige Version von Visual Studio Python-Erweiterungen für alle - Python-Versionen ab Version 3.5 erstellen kann. + Visual Studio is backwards compatible from Python 3.5, which means that + any future version of Visual Studio can create Python extensions for all + Python versions from version 3.5. -Das Erstellen mit dem empfohlenen Compiler unter Windows stellt sicher, dass -eine kompatible C-Bibliothek im gesamten Python-Prozess verwendet wird. +Building with the recommended compiler on Windows ensures that a compatible C +library is used throughout the Python process. -Binary Extensions für Linux +Binary Extensions for Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Linux-Binaries müssen eine ausreichend alte glibc verwenden, um mit älteren -Distributionen kompatibel zu sein. `Distrowatch `_ -bereitet in tabellarischer Form auf, welche Versionen der Distributionen welche -Bibliothek liefern: +Linux binaries must use a sufficiently old glibc to be compatible with older +distributions. `Distrowatch `_ prepares in table form +which versions of the distributions deliver which library: * `Red Hat Enterprise Linux `_ * `Debian `_ * `Ubuntu `_ * … -Das `PYPA/Manylinux `_-Projekt erleichtert -die Distribution von Binary Extensions als :term:`Wheels ` für die -meisten Linux-Plattformen. Hieraus ging auch `PEP 513 -`_ hervor, das die -``manylinux1_x86_64``- und ``manylinux1_i686``-Plattform-Tags definiert. +The `PYPA/Manylinux `_ project facilitates +the distribution of Binary extensions as :term:`Wheels ` for most Linux +platforms. This also resulted in `PEP 513 +`_, which defines the +``manylinux1_x86_64`` and ``manylinux1_i686`` platform tags. -Binary Extensions für Mac +Binary Extensions for Mac ~~~~~~~~~~~~~~~~~~~~~~~~~ -Die Binärkompatibilität auf macOS wird durch das Zielsystem für die minimale -Implementierung bestimmt, z. B. *10.9* , das in der Umgebungsvariable -``MACOSX_DEPLOYMENT_TARGET`` definiert wird. Beim Erstellen mit -setuptools/distutils wird das Deployment-Ziel mit dem Flag ``--plat-name`` -angegeben, z.B. ``macosx-10.9-x86_64``. Weitere Informationen zu -Deployment-Zielen für Mac OS Python-Distributionen findet ihr im `MacPython -Spinning Wheels-Wiki `_. +Binary compatibility on macOS is determined by the target system for the minimal +implementation, e.g. *10.9*, which is defined in the environment variable +``MACOSX_DEPLOYMENT_TARGET``. When creating with setuptools/distutils the +deployment target is specified with the flag ``--plat-name``, for example +``macosx-10.9-x86_64``. For more information on deployment targets for Mac OS +Python distributions, see the `MacPython Spinning Wheels-Wiki +`_. -Deployment von Binary Extensions --------------------------------- +Deployment of binary extensions +------------------------------- -Im Folgenden soll das Deployment auf dem :term:`Python Package Index (PyPI)` -oder einem anderen Index beschrieben werden. +In the following, the deployment on the :term:`Python Package Index (PyPI)` +or another index will be described. .. note:: - Bei Deployments auf Linux-Distributionen sollte beachtet werden, dass diese - Anforderungen an das spezifische Build-System stellen. Daher sollten neben - :term:`Wheels ` immer auch :term:`Source Distributions (sdist) - ` bereitgestellt werden. + When deploying on Linux distributions, it should be noted that these make + demands on the specific build system. Therefore, :term:`Source Distributions + (sdist) ` should also be provided in addition to + :term:`Wheels `. .. seealso:: * `Deploying Python applications diff --git a/docs/productive/packaging/distribution.rst b/docs/productive/packaging/distribution.rst index 31912126..8de6dbcc 100644 --- a/docs/productive/packaging/distribution.rst +++ b/docs/productive/packaging/distribution.rst @@ -1,42 +1,40 @@ -Distribution Package erstellen -============================== +Create a distribution package +============================= -:term:`Distribution Packages ` sind Archive, die in einen -Paket-Index hochgeladen und mit :term:`Pip` installiert werden können. +:term:`Distribution Packages ` are archives that can be +uploaded to a package index and installed with :term:`Pip`. .. note:: - Beachtet bitte, dass es immer noch viele Anleitungen gibt, die einen Schritt - zum Aufruf der ``setup.py`` enthalten, z.B. ``python setup.py sdist``. Dies - wird jedoch heutzutage von Teilen der `Python Packaging Authority (PyPA) - `_ als `Anti-Pattern - `_ angesehen. + Please note that there are still many instructions that contain a step of + calling the ``setup.py``, e.g. ``python setup.py sdist``. However, this is + now seen as an `Anti-Pattern + `_ by parts of the + `Python Packaging Authority (PyPA) `_. ``setup.py`` ------------ -Eine minimale und dennoch funktionale ``setup.py`` findet ihr z.B. im `attrs -`_-Paket: `setup.py -`_. Daran könnt -ihr erkennen, dass das meiste *Boilerplate* ist und lediglich die Zeilen 10–37 -Metadaten für diese spezielle Paket sind. Die meisten anderen Metadaten sind in -der `__init__ -`_ -gespeichert und werden mit regulären Ausdrücken erschlossen. Alternativ können -diese Daten auch in ein separates Modul ausgelagert und mit Python analysiert -werden, wie dies z.B. in `cryptography -`_ -erfolgt. - -In beiden Fällen werden doppelte Metadaten in Paket und Code vermieden. +pyYou can find a minimal yet functional ``setup.py`` in the `attrs +`_ package: `setup.py +`_. This tells you +that most of it is boilerplate and only the lines 10–37 are metadata for this +particular package. Most of the other metadata is stored in the `__init__ +`_ and +is accessed using regular expressions. Alternatively, this data can also be +stored in a separate module and analysed with Python, as it is done in +`cryptography +`_. + +In both cases, duplicate metadata in package and code is avoided. ``src``-Package --------------- -Das `packages`-Feld verwendet setuptools’s `find_packages() +The `packages` field uses setuptools’s `find_packages() `_ -um darunterliegende Pakete zu finden und das `package_dir -`_-Feld -beschreibt, wo das Root-Verzeichnis ist. +to find underlying packages and the `package_dir +`_ +field describes where the root directory is. .. note:: ``find_packages()`` ohne ``src/``-Verzeichnis würde alle Verzeichnisse mit @@ -45,8 +43,8 @@ beschreibt, wo das Root-Verzeichnis ist. ``version`` ----------- -Für ``version`` gibt es verschiedene Möglichkeiten, die in `PEP 0440 -`_ beschrieben sind. +For ``version`` there are different ways described in `PEP 0440 +`_. .. seealso:: * `Semantic Versioning `_ @@ -57,67 +55,65 @@ Für ``version`` gibt es verschiedene Möglichkeiten, die in `PEP 0440 ``classifiers`` --------------- -`classifiers `_ haben eine nützliche -Zusatzfunktion: PyPI lehnt unbekannte *Classifiers* ab, sodass damit auch ein -versehentlicher Upload vermieden werden kann. +`classifiers `_ have a useful additional +function: PyPI rejects unknown classifiers, so that accidental uploads can be +avoided. .. seealso:: `Add invalid classifier for non open source license to avoid upload to… `_ -Abhängigkeiten --------------- +Dependencies +------------ -Versionsnummern von Abhängigkeiten sollten üblicherweise nicht in der -``setup.py`` festgeschrieben werden sondern in der `requirements.txt -`_-Datei. +Version numbers of dependencies should usually not be set in the ``setup.py`` +but in the `requirements.txt +`_. .. seealso:: `setup.py vs requirements.txt `_ -Andere Dateien --------------- +Other files +----------- ``MANIFEST.in`` ~~~~~~~~~~~~~~~ -Die Datei enthält alle Dateien und Verzeichnisse, die nicht bereits mit -``packages`` oder ``py_module`` erfasst werden. Sie kann z.B. so aussehen: +The file contains all files and directories that are not already recorded with +``packages`` or ``py_module``. For example, it could look like this: `attrs/MANIFEST.in `_. -Weitere Anweisungen in `Manifest.in` findet ihr in `Creating a source +Further instructions in `Manifest.in` can be found in `Creating a source distribution `_. .. note:: - Häufig wird die Aktualisierung der ``Manifest.in``-Datei vergessen. Um dies - zu vermeiden, könnt ihr `check-manifest - `_ in einem ``pre-commit``-Hook - verwenden. + Often people forget to update the ``Manifest.in`` file. To avoid this, you + can use `check-manifest `_ in a + ``pre-commit``-hook. .. note:: - Wenn ihr Dateien und Verzeichnisse aus ``MANIFEST.in`` auch installiert - werden sollen, z.B. wenn es sich um laufzeitrelevante Daten handelt, könnt - ihr dies mit ``include_package_data=True`` in eurem ``setup()``-Aufruf - angeben. + If you want to install files and directories from ``MANIFEST.in``, for + example, when it comes to runtime-relevant data, you can specify this with + ``include_package_data=True`` in your ``setup()`` call. ``setup.cfg`` ~~~~~~~~~~~~~ -Diese Datei wird nicht mehr benötigt, zumindest nicht für die Paketierung. -``wheel`` sammelt heutzutage alle erforderlichen Lizenzdateien automatisch und -``setuptools`` kann mit dem ``options``-Keyword-Argument universelle -``whell``-Pakete bauen, z.B. ``attrs-19.3.0-py2.py3-none-any.whl``. +This file is no longer needed, at least not for packaging. Today ``wheel`` +collects all the necessary license files automatically and ``setuptools`` with +the ``options`` keyword argument creates universal ``whell`` packages e.g. +``attrs-19.3.0-py2.py3-none-any.whl``. ``pyproject.toml`` ~~~~~~~~~~~~~~~~~~ -`PEP 517 `_ und `PEP 518 -`_ brachten Plugable Build-Backends, -isolierte Builds und ``pyproject.toml``. Da wir ``setuptools`` verwenden, -sollte die Datei so oder so ähnlich aussehen: +`PEP 517 `_ and `PEP 518 +`_ brought plugable build backends, +isolated builds, and ``pyproject.toml``. Since we’re using ``setuptools``, the +file should look something like this: .. code-block:: toml @@ -128,32 +124,31 @@ sollte die Datei so oder so ähnlich aussehen: ``LICENSE`` ~~~~~~~~~~~ -Einen Überblick über freie und Open-Source-Software-Lizenzen erhaltet ihr in -`Comparison of free and open-source software licenses +You can get an overview of free and open-source software licenses in `Comparison +of free and open-source software licenses `_. -Wenn ihr z.B. eine möglichst große Verbreitung eures Pakets erreichen wollt, -sind MIT- oder die BSD-Varianten eine gute Wahl. Die Apache-Lizenz schützt euch -besser vor Patentverletzungen ist jedoch nicht kompatibel mit der GPL v2. Daher -solltet ihr schauen, welche Lizenzen diejenigen Pakete haben, von denen ihr -abhängt und zu denen ihr kompatibel sein solltet. Zur Analyse von Lizenzen könnt -ihr `licensechecker +For example, if you want to achieve the widest possible distribution of your +package, MIT or BSD variants are a good choice. The Apache license protects you +better against patent infringements, but isn’t compatible with the GPL v2. +Therefore, you should see which licenses have the packages that you depend on +and with which you should be compatible. To analyse licenses, you can use +`licensechecker `_, -verwenden, ein Kommandozeilenwerkzeug, das Installationsverzeichnisse nach -Lizenzen durchsucht. +a command line tool that searches installation directories for licenses. -Darüberhinaus kann es auch sinnvoll sein, ein Package unter mehreren Lizenzen -zu veröffentlichen. Ein Beispiel hierfür ist `cryptography/LICENSE +It can also be useful to publish a package under several licenses. An example of +this is `cryptography/LICENSE `_. ``README.rst`` ~~~~~~~~~~~~~~ -Diese Datei teilt potentiellen Nutzern mit, worauf sie bei der Verwendung des -Pakets achten müssen. Schreibt das Dokument in `ReStructuredText (ReST) +This file tells potential users what to look out for when using the package. +Write the document in `ReStructuredText (ReST) `_, -sodass ihr es später problemlos mit ``.. include:: ../../README.rst`` in die -Sphinx-Dokumentation übernehmen könnt. +so that you can easily transfer it to the Sphinx documentation later with +``.. include:: ../../README.rst``. ``CHANGELOG.rst`` ~~~~~~~~~~~~~~~~~ @@ -165,50 +160,50 @@ Sphinx-Dokumentation übernehmen könnt. Build ----- -Wechselt in das Verzeichnis, in dem sich die ``setup.py``-Datei befindet. +Change to the directory in which the ``setup.py`` file is located. .. code-block:: console $ rm -rf build dist $ pipenv run python3 -m pep517.build . -Die erste Zeile stellt sicher, dass ein sauberes Build ohne Artefakte -früherer Builds erstellt wird. Die zweite Zeile baut ein ``sdist``-Archiv unter -Linux/Mac als gezippte Tar-Datei (``.tar.gz``) und unter Windows eine ZIP-Datei -sowie ein ``bdist_wheel``-Archiv mit ``.whl`` im ``dist``-Verzeichnis. +The first line ensures that a clean build is produced with no artifacts from +previous builds. The second line builds an ``sdist`` archive under Linux/Mac as +a zipped tar file (``.tar.gz``) and under Windows a ZIP file as well as an +``bdist_wheel`` archive ``.whl`` in the ``dist`` directory. -Dieser Befehl sollte also die folgenden beiden Dateien erzeugen:: +So this command should produce the following two files: dist/ example-0.0.1-py3-none-any.whl example-0.0.1.tar.gz ``py3`` - Python-Version, mit der das Paket gebaut wurde + Python version that the package was built with ``none`` - nicht OS-spezifisch + not OS specific ``any`` - geeignet für jede Prozessorarchitektur + suitable for every processor architecture -Die Referenz für die Dateinamen findet ihr in `File name convention +You can find the reference for the file names in `File name convention `_. .. seealso:: - Weitere Infos zu ``sdist`` erhaltet ihr in `Creating a Source Distribution + For more information, see `Creating a Source Distribution `_. - und `PEP 376 `_. + and `PEP 376 `_. .. note:: - Die Verwendung von `pep517.build `_ - zum Erstellen von Paketen ist aktuell (Oktober 2019) noch `etwas umstritten + The use of `pep517.build `_ + to create packages is currently (October 2019) a `bit controversial `_. - Es scheint Konsens zu sein, dass diese Funktionalität entweder in Pip oder in Twine - zusammengeführt werden sollte. Derzeit scheint der oben genannte Weg jedoch der - sauberste zu sein, ein Paket zu erstellen. Ich werde diesen Artikel - aktualisieren, sobald sich eine andere Lösung durchsetzt. + There seems to be a consensus that this functionality should be merged into + either Pip or Twine. At the moment, however, the above seems like the + cleanest way to package a package. I will update this article as soon as + another solution prevails. -Testen ------- +Testing +------- .. code-block:: console @@ -223,7 +218,7 @@ Testen >>> import attr; attr.__version__ '19.3.0' -oder +or .. code-block:: console diff --git a/docs/productive/packaging/example.rst b/docs/productive/packaging/example.rst index 9cc15b50..a0fb04b1 100644 --- a/docs/productive/packaging/example.rst +++ b/docs/productive/packaging/example.rst @@ -1,9 +1,9 @@ -Beispiel -======== +Example +======= -#. Notebooks sind gut geeignet um schnell voranzukommen, doch bei umfangreicher - werdendem Code empfiehlt sich, stabilen Code in Module auszulagern. Wenn ihr - z.B. in eurem Notebook geschrieben habt: +#. Notebooks are well suited for making rapid progress, but when the code + becomes more extensive, it is advisable to move stable code into modules. For + example, if you wrote in your notebook: .. code-block:: python @@ -12,7 +12,7 @@ Beispiel df.query( ... df.groupby( ... - so könnt ihr das in eine Datei ``dataprep.py`` auslagern + so you can outsource it to a file ``dataprep.py``: .. code-block:: python @@ -22,15 +22,15 @@ Beispiel # ... return df - und dies kann wieder in das Notebook übernommen werden mit + and this can be imported into the notebook with .. code-block:: python import dataprep df = dataprep.load_and_preprocess_data(filename) - Wenn ihr das Python-Skript ändert, kann die aktualiserte Variante automatisch - übernommen werden mit :mod:`IPython.extensions.autoreload`: + If you change the Python script, the updated variant can be automatically + adopted with :mod:`IPython.extensions.autoreload`: .. code-block:: python diff --git a/docs/productive/packaging/index.rst b/docs/productive/packaging/index.rst index 45c89f92..7eb97af4 100644 --- a/docs/productive/packaging/index.rst +++ b/docs/productive/packaging/index.rst @@ -1,31 +1,29 @@ -Pakete erstellen -================ +Create packages +=============== -#. Notebooks sind gut geeignet um schnell voranzukommen, doch bei umfangreicher - werdendem Code empfiehlt sich, stabilen Code in Pakete auszulagern. -#. Ihr könnt :ref:`pytest ` nicht nur - innerhalb Eurer Notebooks zum Testen verwenden, sondern auch innerhalb Eurer - Pakete. -#. Verwendet `Clean Code `_-Prinzipien - mit aussagekräftigen Variablen- und Funktionsnamen, kommentiert sinnvoll - und modularisiert den Code. +#. Notebooks are well suited for moving forward quickly, but when the code + becomes more extensive, it is advisable to store stable code in packages. +#. You can use :ref:`pytest ` not only within + your notebooks for testing, but also within your packages. +#. Use Clean Code principles with meaningful variable and function names, make + meaningful comments and modularise the code. - Es gibt auch Werkzeuge, die automatisch Coding-Styles anwenden wie z.B. - `PEP 8 `_ für Python. Mit - :doc:`nbextensions/code_prettify/README_autopep8` könnt Ihr dies nicht nur - auf Eure Notebooks anwenden, sondern z.B. mit `black - `_ auch auf Eure Python-Pakete. + There are also tools that automatically apply coding styles such as `PEP 8 + `_ for Python. With + :doc:`nbextensions/code_prettify/README_autopep8` you can not only apply this + to your notebooks, but also to your Python packages, for example with `black + `_. - Für andere Sprachen findet Ihr Übersichten in `Awesome-Linters - `_ und `awesome-code-formatters + For other languages ​​you can find overviews in `Awesome-Linters + `_ and `awesome-code-formatters `_. - Ihr könnt diese Werkzeuge mit einem Pre-Commit-Hock automatisch vor jedem - ``git commit`` ausfähren, z.B. `mirrors-autopep8 + You can automatically execute these tools with a pre-commit hock in front of + every, ``git commit``, e.g. `mirrors-autopep8 `_, `pygrep-hooks - `_ oder `blacken-docs - `_. Eine gute Übersicht über - verfügbare Git Pre-Commit-Hocks erhaltet Ihr auf `pre-commit.com + `_ or `blacken-docs + `_. You can get a good overview of + available Git pre-commit hocks at `pre-commit.com `_. .. seealso:: diff --git a/docs/productive/packaging/next-steps.rst b/docs/productive/packaging/next-steps.rst index 30924222..09043b88 100644 --- a/docs/productive/packaging/next-steps.rst +++ b/docs/productive/packaging/next-steps.rst @@ -1,21 +1,19 @@ -Nächste Schritte -================ +Next steps +========== -Denkt bitte daran, dass ihr nun euer Paket zu *Test-PyPI* hochladen könnt und -dass die Pakete auf *Test-PyPI* nur temporär gespeichert werden. Wenn ihr ein -Paket in den echten :term:`Python Package Index (PyPI)` hochladen wollt, könnt -ihr dies tun, indem ihr ein Konto auf https://pypi.org anlegt und die gleichen -Anweisungen befolgt, jedoch ``twine upload dist/*`` verwendet. +Pleas keep in mind that your package on *Test-PyPI* is only stored temporarily. +If you want to upload a package to the real :term:`Python Package Index (PyPI)`, +you can do so by creating an account on https://pypi.org and following the same +instructions, but using ``twine upload dist/*``. -Und wenn ihr mehr über Python-Bibliotheken erfahren wollt, könnt ihr +And if you want to learn more about Python libraries, you can -* weiterlesen, wie `setuptools - `_ verwendet werden - kann zum Packen und Verteilen von Paketen: `Packaging and distributing - projects +* read more about how `setuptools + `_ can be used to pack + and distribute packages: `Packaging and distributing projects `_. -* Alternativen zu `setuptools - `_ anschauen wie +* look at alternatives to `setuptools + `_ like `flit `_, - `hatch `_ und + `hatch `_ and `poetry `_. diff --git a/docs/productive/packaging/templating/advanced.rst b/docs/productive/packaging/templating/advanced.rst index 5967ad96..2ad4b812 100644 --- a/docs/productive/packaging/templating/advanced.rst +++ b/docs/productive/packaging/templating/advanced.rst @@ -1,18 +1,18 @@ -Fortgeschrittene Nutzung -======================== +Advanced usage +============== Hooks ----- -Ihr könnt Pre- oder Post-Generate-Hooks schreiben. Dabei werden die -Jinja-Template-Variablen in die Skripte integriert werden, z.B.: +You can write pre- or post-generate hooks. The Jinja template variables will be +integrated into the scripts, for example: .. code-block:: python if 'Not open source' == '{{ cookiecutter.license }}': remove_file('LICENSE') -In einem Pre-Generate-Hook können z.B. Variablen validiert werden: +Variables, for example, can be validated in a pre-generate hook: .. code-block:: python @@ -30,11 +30,11 @@ In einem Pre-Generate-Hook können z.B. Variablen validiert werden: # exits with status 1 to indicate failure sys.exit(1) -User Config +User config ----------- -Wenn ihr Cookiecutter häufig verwendet, empfiehlt sich eine eigene User-Config: -``~/cookiecutterrc``, z.B.: +If you use CookieCutter frequently, we recommend your own user config +``~/cookiecutterrc``, e.g.: .. code-block:: bash @@ -48,38 +48,37 @@ Wenn ihr Cookiecutter häufig verwendet, empfiehlt sich eine eigene User-Config: Replay ------ -Beim Aufruf von ``cookiecutter`` wird eine ``json``-Datei angelegt in -``/.cookiecutter_replay/``, z.B. +When calling ``cookiecutter`` a ``json`` file is created in +``/.cookiecutter_replay/``, for example ``~/.cookiecutter_replay/cookiecutter-namespace-template.json``: .. code-block:: json {"cookiecutter": {"full_name": "Veit Schiele", "email": "veit@cusy.io", "github_username": "veit", "project_name": "vsc.example", "project_slug": "vsc.example", "namespace": "vsc", "package_name": "example", "project_short_description": "Python Namespace Package contains all you need to create a Python namespace package.", "pypi_username": "veit", "use_pytest": "y", "command_line_interface": "Click", "version": "0.1.0", "create_author_file": "y", "license": "MIT license", "_template": "https://github.com/veit/cookiecutter-namespace-template"}} -Sollen diese Informationen verwendet werden ohne diese erneut in der -Kommandozeile bestätigen zu müssen, könnt ihr einfach z.B. folgendes eingeben: +If you want to use this information without having to confirm them again in the +command line, you can simply enter the following: .. code-block:: console $ cookiecutter --replay gh:veit/cookiecutter-namespace-template -Alternativ kann auch die Python-API verwendet werden: +Alternatively, the Python API can also be used: .. code-block:: python from cookiecutter.main import cookiecutter cookiecutter('gh:'veit/cookiecutter-namespace-template, replay=True) -Diese Funktion ist hilfreich, wenn ihr z.B. ein Projekt aus einer aktualisierten -Vorlage erstellen wollt. +This function is helpful if you want to create a project from an updated +template, for example. -Auswahlvariablen ----------------- +Selection variables +------------------- -Auswahlvariablen bieten verschiedene Möglichkeiten beim Erstellen eines -Projekts. Abhängig von der Wahl des Benutzers rendert die Vorlage diese -anders, z.B. wenn in der ``cookiecutter.json``-Datei folgende Auswahl angeboten -wird: +Selection variables offer various options when creating a project. Depending on +the user’s choice, the template renders it differently, e.g. if in the +``cookiecutter.json`` file the following selection is offered: .. code-block:: json @@ -87,7 +86,7 @@ wird: "license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Other/Proprietary License"] } -Dies wird dann ausgewertet in +This is interpreted in ``cookiecutter-namespace-template/{{cookiecutter.project_name}}/README.rst`` .. code-block:: jinja @@ -101,7 +100,7 @@ Dies wird dann ausgewertet in … {% endif %} -und in ``cookiecutter-namespace-template/hooks/post_gen_project.py``: +and in ``cookiecutter-namespace-template/hooks/post_gen_project.py``: .. code-block:: python diff --git a/docs/productive/packaging/templating/features.rst b/docs/productive/packaging/templating/features.rst index 1854a7b1..dafd5bb3 100644 --- a/docs/productive/packaging/templating/features.rst +++ b/docs/productive/packaging/templating/features.rst @@ -1,12 +1,12 @@ -CookieCutter-Features +CookieCutter features ===================== -* Cross-platform: Windows, Mac und Linux werden unterstützt -* Funktioniert mit Python 3.6, 3.7, 3.8 und PyPy3 -* Die Projektvorlagen können für jede Programmiersprache und jedes - Markup-Format erstellt werden: Python, JavaScript, Ruby, ReST, CSS, HTML. - Es können auch mehrere Sprachen im selben Template verwendet werden. -* Templates lassen sich einfach im Terminal anpassen: +* Cross-platform: Windows, Mac and Linux are supported +* works with Python 3.6, 3.7, 3.8 and PyPy3 +* The project templates can be created for any programming language and any + markup format: Python, JavaScript, Ruby, ReST, CSS, HTML. Several languages + can also be used in the same template. +* Templates can be easily adapted in the terminal: .. code-block:: console @@ -14,13 +14,13 @@ CookieCutter-Features full_name [Veit Schiele]: … -* Ihr könnt auch lokale Templates verwenden: +* You can also use local templates: .. code-block:: console $ cookiecutter cookiecutter-namespace-template -* Alternativ könnt ihr CookieCutter auch mit Python verwenden: +* Alternatively you can also use CookieCutter with Python: .. code-block:: console @@ -30,16 +30,16 @@ CookieCutter-Features full_name [Veit Schiele]: … -* Verzeichnis- und Dateinamen können Vorlagen zugewiesen werden, z.B.: +* Directory and file names can be assigned to templates, for example: .. code-block:: jinja {{cookiecutter.project_name}}/{{cookiecutter.namespace}}/{{cookiecutter.package_name}}/{{cookiecutter.project_slug}}.py -* Die Verschachtelungstiefe ist unbegrenzt -* Das Templating basiert auf `Jinja2 `_ -* Ihr könnt eure Template-Variablen einfach in einer ``cookiecutter.json``-Datei - speichern, beispielsweise: +* The nesting depth is unlimited +* The templating is based on `Jinja2 `_ +* You can simply save your template variables in a ``cookiecutter.json`` file, + for example: .. code-block:: json @@ -60,8 +60,7 @@ CookieCutter-Features "license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"] } -* Ihr könnt die Werte auch für mehrere Vorlagen hinterlegen in - ``~/cookiecutterrc``: +* You can also save the values for several templates in ``~/cookiecutterrc``: .. code-block:: bash @@ -71,9 +70,9 @@ CookieCutter-Features github_username: "veit" cookiecutters_dir: "~/.cookiecutters/" -* CookieCutter-Templates, die aus einem Repository geladen wurden, werden - üblicherweise in ``~/.cookiecutters/`` gespeichert. Anschließend können sie - direkt über ihren Verzeichnisnamen referenziert werden, also z.B. mit: +* CookieCutter templates loaded from a repository are usually stored in + ``~/.cookiecutters/``. Then they can be referenced directly via their + directory name, e.g. with: .. code-block:: console diff --git a/docs/productive/packaging/templating/index.rst b/docs/productive/packaging/templating/index.rst index 22309756..e3803419 100644 --- a/docs/productive/packaging/templating/index.rst +++ b/docs/productive/packaging/templating/index.rst @@ -1,9 +1,8 @@ Templating ========== -Mit `Cookiecutter `_ lassen sich -Dateistrukturen erstellen, die u.a. das Erstellen von Python-Paketen deutlich -vereinfachen. +With `Cookiecutter `_, file structures +can be created which simplify the creation of Python packages significantly. .. toctree:: :hidden: diff --git a/docs/productive/packaging/templating/install.rst b/docs/productive/packaging/templating/install.rst index 7dcadcb3..d31fa903 100644 --- a/docs/productive/packaging/templating/install.rst +++ b/docs/productive/packaging/templating/install.rst @@ -1,27 +1,27 @@ Installation ============ -Voraussetzungen ---------------- +Requirements +------------ -* Python-Interpreter +* Python interpreter -* Pfad zum Basisverzeichnis für euere Python-Pakete +* Path to the base directory for your Python packages - Stellt sicher, dass sich euer ``bin``-Verzeichnis im Pfad befindet. In der - Regel ist dies ``~/.local/`` für Linux und Mac OS oder ``%APPDATA%\Python`` - unter Windows. Weitere Infos findet ihr in `site.USER_BASE + Make sure your ``bin`` bindirectory is in the path. Usually this is + ``~/.local/`` for Linux and Mac OS or ``%APPDATA%\Python``. on Windows. You + can find more information at `site.USER_BASE `_. - * Linux und MacOS + * Linux and MacOS - Für Bash könnt ihr den Pfad in eurer ``~/.bash_profile`` angeben: + For bash you can enter the path in your ``~/.bash_profile``: .. code-block:: bash export PATH=$HOME/.local/bin:$PATH - und anschließend die Datei einlesen mit: + and then read the file with: .. code-block:: console @@ -29,12 +29,11 @@ Voraussetzungen * Windows - Stellt sicher, dass das Verzeichnis, in dem CookieCutter installiert wird, - sich in eurem ``Path`` befindet, damit ihr es direkt aufrufen könnt. Sucht - dazu auf Ihrem Computer nach *Environment Variables* und fügt dieses - Verzeichnis zu ``Path`` hinzu, also z.B. ``%APPDATA%\Python\Python3x\Scripts``. - Anschließend müsst ihr vermutlich die Session neu starten um die - Umgebungsvariablen nutzen zu können. + Make sure the directory where CookieCutter will be installed is in your + ``Path`` so you can go directly to it. To do this, look for *Environment + Variables* on your computer and add this directory to ``Path``, for + example ``%APPDATA%\Python\Python3x\Scripts``. Then you probably have to + restart the session in order to be able to use the environment variables. .. seealso:: `Configuring Python diff --git a/docs/productive/packaging/templating/overview.rst b/docs/productive/packaging/templating/overview.rst index c6d820dd..34c9160d 100644 --- a/docs/productive/packaging/templating/overview.rst +++ b/docs/productive/packaging/templating/overview.rst @@ -1,7 +1,7 @@ -Übersicht -========= +Overview +======== -Ein minimales CookieCutter-Template sieht so aus: +A minimal CookieCutter template looks like this: .. code-block:: console @@ -10,7 +10,7 @@ Ein minimales CookieCutter-Template sieht so aus: │ └── … └── cookiecutter.json <--- Prompts & default values -Die ``cookiecutter.json``-Datei kann beispielsweise so aussehen: +For jsonexample, the file ``cookiecutter.json`` can look like this: .. code-block:: json @@ -31,9 +31,9 @@ Die ``cookiecutter.json``-Datei kann beispielsweise so aussehen: "license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"] } -Darüberhinaus können beliebige Verzeichnisse und Dateien angelegt werden. +In addition, any number of directories and files can be created. -Als Ergebnis erhaltet ihr dann folgende Dateistruktur: +As a result you will get the following file structure: .. code-block:: console diff --git a/docs/productive/packaging/templating/templates.rst b/docs/productive/packaging/templating/templates.rst index 2de5d211..936488d6 100644 --- a/docs/productive/packaging/templating/templates.rst +++ b/docs/productive/packaging/templating/templates.rst @@ -1,66 +1,66 @@ -Verfügbare Templates -==================== +Available templates +=================== Python ------ `cookiecutter-namespace-template `_ - Namespace-Template für Python-Pakete + Namespace template for Python packages `cookiecutter-pypackage `_ - Template für Python-Pakete + Template for Python packages `cookiecutter-pytest-plugin `_ - Minimales Cookiecutter-Template zum Erstellen von `Pytest - `_-Plugins + Minimal CookiexrCtter template for creating `Pytest + `_ plugins `cookiecutter-pylibrary `_ - Umfangreiche Vorlage für Python-Pakete mit Unterstützung für Tests und - Deployments (C-Extension-Support u.a. für `cffi - `_ und `Cython `_, - Test-Unterstützung für `Tox `_, + Comprehensive template for Python packages with support for tests and + Deployments (C extension support for `cffi + `_ and `Cython `_, + test support for `Tox `_, `Pytest `_, `Travis-CI `_, `Coveralls `_, `Codacy `_, - und `Code Climate `_, - Dokumentation mit `Sphinx `_, - Packaging-Checks u.a. mit `Landscape `_, + and `Code Climate `_, + documentation with `Sphinx `_, + packaging checks with `Landscape `_, `scrutinizer `_, `Isort `_ etc. `cookiecutter-python-cli `_ - Template zum Erstellen einer Python-CLI-Anwendung mit `Click `_ + Template for creating a Python CLI application with `Click `_ `widget-cookiecutter `_ - Template zum Erstellen von Jupyter-Widgets + Template for creating Jupyter widgets Ansible ------- `cookiecutter-ansible-role-ci `_ - Vorlage für Ansible-Roles + Template for Ansible roles C ---- +- `bootstrap.c `_ - Template für in C mit `Autotools - `_ geschriebene Projekte + Template for projects written in C with `Autotools + `_ `cookiecutter-avr `_ - Template für die AVR-Entwicklung + Template for AVR development C++ --- `BoilerplatePP `_ - cmake-Template mit Unit Tests für C++-Projekte + cmake template with unit tests for C ++ projects Scala ----- `cookiecutter-scala `_ - Vorlage für ein *Hello world*-Beispiel mit ein paar wenigen Bibliotheken + Template for a Hello world example with a few libraries `cookiecutter-scala-spark `_ - Template für eine `Apache-Spark `_-Anwendung + Template for an `Apache-Spark `_ application LaTeX/XeTeX ----------- `pandoc-talk `_ - Template für Präsentation mit `pandoc `_ und `XeTeX + Template for presentations with `pandoc `_ and `XeTeX `_ diff --git a/docs/productive/packaging/upload-install.rst b/docs/productive/packaging/upload-install.rst index a79e60ed..5a52557b 100644 --- a/docs/productive/packaging/upload-install.rst +++ b/docs/productive/packaging/upload-install.rst @@ -1,16 +1,15 @@ Upload ====== -Schließlich solltet ihr das Paket auf dem :term:`Python Package Index (PyPI)` -oder einem anderen Index bereitstellen. +Finally, you should provide the package on the :term:`Python Package Index +(PyPI)` or another index. -Hierfür solltet ihr euch bei *Test PyPI* registrieren. *Test-PyPI* ist eine -separate Instanz, die zum Testen und Experimentieren vorgesehen ist. Um dort -ein Konto einzurichten, geht ihr auf https://test.pypi.org/account/register/. -Weitere Informationen findet ihr unter `Using TestPyPI -`_. +For this you should register on *Test PyPI*. *Test-PyPI* is a separate instance +that is intended for testing and experimentation. To set up an account there, go +to https://test.pypi.org/account/register/. For more information, see `Using +TestPyPI `_. -Nun könnt ihr eine ``~/.pypirc``-Datei erstellen: +Now you can create the ``~/.pypirc`` file: .. code-block:: ini @@ -23,13 +22,13 @@ Nun könnt ihr eine ``~/.pypirc``-Datei erstellen: username = veit .. seealso:: - Wenn ihr die PyPI-Anmeldung automatisieren wollt, lest bitte `Careful With - That PyPI + If you’d like to automate PyPI registration, please read `Careful With That + PyPI `_. -Nachdem ihr registriert seid, könnt ihr euer :term:`Distribution Package` mit -`twine `_ hochladen. Hierzu -müsst ihr jedoch zunächst twine installieren mit: +After you are registered, you can upload your :term:`Distribution Package` with +`twine `_ To do this, however, +you must first install twine with: .. code-block:: console @@ -38,11 +37,11 @@ müsst ihr jedoch zunächst twine installieren mit: All dependencies are now up-to-date! .. note:: - Führt diesen Befehl vor jedem Release aus um sicherzustellen, dass alle - Release-Tools auf dem neuesten Stand sind. Die restlichen Build-Tools werden - von pep517 automatisch in der isolierten Build-Umgebung installiert. + Run this command before each release to ensure that all release tools are up + to date. The remaining build tools are automatically installed in the + isolated build environment by pep517. -Nun könnt ihr eure *Distribution Packages* erstellen mit: +Now you can create your *Distribution Packages* with: .. code-block:: console @@ -50,24 +49,23 @@ Nun könnt ihr eure *Distribution Packages* erstellen mit: $ pipenv run python -m pep517.build . … -Nach der Installation von Twine könnt ihr alle Archive unter ``/dist`` auf den -Python Package Index hochladen mit: +After installing Twine you can upload all archives in ``/dist`` to the Python +Package Index with: .. code-block:: console $ pipenv run twine upload -r test -s dist/* ``-r``, ``--repository`` - Das Repository zum Hochladen des Pakets. + The repository to upload the package. - In unserem Fall wird ``test``-Abschnitt aus der ``~/.pypirc``-Datei - verwendet. + In our case, the ``test`` section from the ``~/.pypirc`` file is used. ``-s``, ``--sign`` - signiert die hochzuladenden Dateien mit GPG. + signs the files to be uploaded with GPG. -Ihr werdet nach eurem Passwort gefragt, mit dem ihr euch bei *Test PyPI* -registriert habt. Anschließend solltet ihr eine ähnliche Ausgabe sehen: +You will be asked for the password you used to register on *Test PyPI*. You +should then see a similar output: .. code-block:: console @@ -80,27 +78,26 @@ registriert habt. Anschließend solltet ihr eine ähnliche Ausgabe sehen: 100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s] .. note:: - Wenn ihr eine ähnliche Fehlermeldung erhaltet wie + If you get an error message similar to .. code-block:: console The user 'veit' isn't allowed to upload to project 'example' - müsst ihr einen eindeutigen Namen für euer Paket auswählen: + you have to choose a unique name for your package: - #. ändert das ``name``-Argument in der ``setup.py``-Datei - #. entfernt das ``dist``-Verzeichnis - #. generiert die Archive neu + #. change the ``name`` argument in the ``setup.py`` file + #. remove the ``dist`` directory + #. regenerate the archives -Überprüfen ----------- +Check +----- Installation ~~~~~~~~~~~~ -Ihr könnt :term:`pipenv` verwenden um euer Paket zu installieren und zu überprüfen, -ob es funktioniert. Erstellt eine neue :term:`virtuelle Umgebung` und -installiert euer Paket von *Test PyPI*: +You can use :term:`pipenv` to install your package and check if it works. Create +a new :term:`virtual environment` and install your package on *Test PyPI*: .. code-block:: console @@ -109,11 +106,11 @@ installiert euer Paket von *Test PyPI*: $ pipenv install --extra-index-url https://test.pypi.org/simple/ minimal_example .. note:: - Wenn ihr einen anderen Paketnamen verwendet habt, ersetzt ihn im obigen - Befehl durch euren Paketnamen. + If you have used a different package name, replace it with your package name + in the command above. -:term:`pip` sollte das Paket von *Test PyPI* installieren und die Ausgabe sollte -in etwa so aussehen: +:term:`pip` should install the package from *Test PyPI* and the output should +look something like this: .. code-block:: console @@ -122,9 +119,9 @@ in etwa so aussehen: Installing collected packages: minimal_example Successfully installed minimal_example-0.0.1 -Ihr könnt testen, ob euer Paket korrekt installiert wurde indem ihr das Modul -importiert und auf die ``name``-Eigenschaft referenziert, die zuvor in -``__init__.py`` eingegeben wurde: +You can test whether your package has been installed correctly by importing the +module and referencing the ``name`` property that was previously ntered in +``__init__.py``: .. code-block:: console @@ -138,16 +135,16 @@ importiert und auf die ``name``-Eigenschaft referenziert, die zuvor in README ~~~~~~ -Überprüft bitte auch, ob die ``README.rst``-Datei auf der Test-PyPI-Seite -korrekt angezeigt wird. +Please also check whether the ``README.rst`` is displayed correctly on the test +PyPI page. PyPI ---- -Registriert euch nun beim :term:`Python Package Index (PyPI)` und stellt sicher, -dass die `Zwei-Faktor-Authentifizierung +Now register on the :term:`Python Package Index (PyPI)` and make sure that +`two-factor authentication `_ -aktiviert ist indem ihr die ``~/.pypirc``-Datei ergänzt: +is activated by adding the following to the ``~/.pypirc`` file: .. code-block:: ini @@ -163,8 +160,8 @@ aktiviert ist indem ihr die ``~/.pypirc``-Datei ergänzt: [pypi] username = __token__ -Mit dieser Konfiguration wird nicht mehr die Name/Passwort-Kombination beim -Hochladen verwendet sondern ein Upload-Token. +With this configuration, the name/password combination is no longer used for +uploading but an upload token. .. seealso:: * `PyPI now supports uploading via API token @@ -172,16 +169,16 @@ Hochladen verwendet sondern ein Upload-Token. * `What is two factor authentication and how does it work on PyPI? `_ -Schließlich könnt ihr nun euer Paket auf PyPI veröffentlichen: +Finally, you can publish your package on PyPI: .. code-block:: console $ pipenv run twine upload -r pypi -s dist/* .. note:: - Ihr könnt Releases von PyPI löschen, aber nicht unter derselben - Versionsnummer erneut hochladen! Seit also vor dem Löschen und Hochladen - vorsichtig: Releases können nicht einfach ersetzt werden. + You can delete PyPI releases, but you cannot upload them again under the + same version number! So be careful before deleting and uploading: Releases + cannot simply be replaced. .. seealso:: * `PyPI Release Checklist diff --git a/docs/productive/quote/authorship.rst b/docs/productive/quote/authorship.rst index d2a070ef..bff728d4 100644 --- a/docs/productive/quote/authorship.rst +++ b/docs/productive/quote/authorship.rst @@ -1,9 +1,9 @@ -Autorenschaft -============= +Authorship +========== -Bedauerlicherweise gibt es keine anerkannten Richtlinien für die Urheberschaft -von Software. Neben der Rolle *programmers* können auch andere Rollen wie z.B. -*software architects*, *technical writers* und *maintainers* definiert werden. +Unfortunately, there are no recognized guidelines for software authorship. In +addition to the *programmers* role, other roles such as *software architects*, +*technical writers* and *maintainers* can also be defined. .. seealso:: * `ICMJE: Defining the Role of Authors and Contributors diff --git a/docs/productive/quote/index.rst b/docs/productive/quote/index.rst index 3b56d657..0239263c 100644 --- a/docs/productive/quote/index.rst +++ b/docs/productive/quote/index.rst @@ -1,45 +1,40 @@ -Zitieren -======== - -Heute ist Software ein integraler Bestandteil wissenschaftlicher Forschung. Mit -ihr werden Forschungsdaten erstellt, verarbeitet und analysiert sowie komplexe -Prozesse modelliert und simuliert. Trotz ihrer zunehmenden Bedeutung in der -Forschung ist kaum bekannt, wie sie in die wissenschaftlichen Anerkennungs- -und Reputationssysteme eingebettet werden können. -Eine wesentliche Möglichkeit in diesen Systemen sind Zitate, wobei jedoch nur -wenige Forscher*innen wissen, wie Software zitiert werden könnte. James Howison -und Julia Bullard führten in ihrem 2016 veröffentlichten Artikel `Software in -the scientific literature `_ folgende -Beispiele in absteigender Reputation auf: - -#. zitieren von Veröffentlichungen, die die jeweilige Software beschreiben -#. zitieren von Bedienungsanleitungen -#. zitieren der Software-Projekt-Website -#. Link auf eine Software-Projekt-Website -#. erwähnen des Software-Namens - -Die Situation bleibt dennoch unbefriedigend für die Autor*innen von Software, -zumal wenn sie sich von den Autor*innen der Software-Beschreibung unterscheiden. -Umgekehrt ist Forschungssoftware leider auch nicht immer gut geeignet um zitiert -zu werden. So werden Kollegen Eure Software kaum direkt zitieren können, wenn Ihr -ihnen die Software als Anhang von E-Mails schickt. Auch ein Download-Link ist -hier noch nicht wirklich zielführend. Aber wie können Autor*innen ihre Software -zitierfähig bereitstellen? - -Die `FORCE11 `_ --Arbeitsgruppe hat ein Paper veröffentlicht, in denen Prinzipien des -wissenschaftlichen Software-zitierens dargelegt werden: Arfon Smith, Daniel -Katz, Kyle Niemeyer: `FORCE11 Software Citation Working Group -`_, 2016. Dabei kristallisieren sich -aktuell zwei Projekte für strukturierte Metadaten heraus: +Citing +====== + +Today software is an integral part of scientific research. It is used to create, +process and analyse research data and to model and simulate complex processes. +Despite their increasing importance in research, it’s little known how it can be +embedded in the scientific recognition and reputation systems. Quotations are an +essential option in these systems, but few researchers know how software could +be cited. James Howison and Julia Bullard listed the following examples in +descending reputations in their 2016 article `Software in the scientific +literature `_: + +#. citing publications that describe the respective software +#. citing operating instructions +#. citing the software project website +#. link to a software project website +#. mention the software name + +Nevertheless, the situation remains unsatisfactory for software authors, +especially if they differ from the authors of the software description. +Conversely, research software is unfortunately not always well suited to be +cited. Colleagues will hardly be able to cite your software directly if you send +them the software as an attachment to an email. Even a download link is not +really useful here. But how can authors make their software citable? + +The `FORCE11 `_ +working group has published a paper in which the principles of scientific +software citation are presented: `FORCE11 Software Citation Working Group +`_ by Arfon Smith, Daniel Katz and Kyle +Niemeyer 2016. Two projects are currently emerging for structured metadata: `CodeMeta `_ - Austauschschema für allgemeine Software-Metadaten und - Referenzimplementierung für JSON for Linking Data (`JSON-LD - `_). + Exchange scheme for general software metadata and reference implementation + for JSON for Linking Data (`JSON-LD `_). - Dabei wird eine ``codemeta.json``-Datei im Stammverzeichnis des - Software-Repository erwartet. Die Datei kann z.B. so aussehen: + A ``codemeta.json`` file is expected in the root directory of the software + repository. The file can look like this: .. code-block:: javascript @@ -66,15 +61,15 @@ aktuell zwei Projekte für strukturierte Metadaten heraus: `_ `Citation File Format `_ - Schema für Software-Citation-Metadaten in maschinenlesbarem `YAML - `_-Format + Scheme for software citation metadata in machine-readable `YAML + `_ format - Dabei sollte eine Datei ``CITATION.cff`` im Stammverzeichnis des - Software-Repository abegelgt werden. + A file ``CITATION.cff`` should be stored in the root directory of the + software repository. - Der Inhalt der Datei kann z.B. so aussehen: + The content of the file can look like this: - .. code-block:: yaml + .. code-block:: # YAML 1.2 --- @@ -89,28 +84,26 @@ aktuell zwei Projekte für strukturierte Metadaten heraus: doi: 10.5281/zenodo.1234 date-released: 2017-12-18 - Ihr könnt einfach das obige Beispiel anpassen um Eure eigene - ``CITATION.cff``-Datei zu erzeugen oder die Website `cffinit + You can easily adapt the example above to create your own ``CITATION.cff`` + file or use the `cffinit `_ - verwenden. + website. - Es gibt auch einige Tools zum Verarbeiten von ``CITATION.cff``-Dateien: + There are also some tools for processing ``CITATION.cff`` files: * `cff-converter-python `_ - konvertiert ``CITATION.cff``-Dateien in BibTeX, RIS, CodeMeta- und - andere Dateiformate - * `doi2cff `_ erstellt - eine ``CITATION.cff``-Datei aus einem Zenodo DOI - -Ihr solltet einen `Persistent Identifier (PID) -`_ bereitstellen um die -langfristige Verfügbarkeit Eurer Software sicherzustellen. Sowohl das `Zenodo -`_- als auch das `figshare -`_-Repository akzeptieren Quellcode einschließlich -Binärdateien und stellen DOIs hierfür breit. Und auch mit `CiteAs -`_ lassen sich Zitierinformationen für Software -abrufen. + converts ``CITATION.cff`` files to BibTeX, RIS, CodeMeta and other file + formats + * `doi2cff `_ creates a + ``CITATION.cff`` file from a Zenodo DOI + +You should provide a `Persistent Identifier (PID) +`_ to ensure the long-term +availability of your software. Both the `Zenodo `_ and +`figshare `_ repositories accept source code including +binary files and provide DOIs for this. And citation information for software +can also be called up with `CiteAs `_. .. seealso:: * `Should I cite? `_ diff --git a/docs/productive/quote/journals.rst b/docs/productive/quote/journals.rst index 91f05730..ca6265dc 100644 --- a/docs/productive/quote/journals.rst +++ b/docs/productive/quote/journals.rst @@ -1,8 +1,8 @@ -Software-Journale +Software journals ================= -Allgemein ---------- +General +------- * `IEEE Computer Society Digital Library `_ * `Wiley Online Library @@ -21,14 +21,14 @@ Allgemein * `SoftwareX `_ -Bildverarbeitung +Image processing ---------------- * `Image Processing On Line `_ * `Insight Journal `_ -Biologie --------- +Biology +------- * `American Journal of Human Genetics `_ * `Artificial Life `_ @@ -67,8 +67,8 @@ Biologie * `PLoS ONE `_ * `Trends in Parasitology `_ -Chemie ------- +Chemistry +--------- * `International Journal of Quantum Chemistry `_ @@ -84,8 +84,8 @@ Chemie * `Wiley Interdisciplinary Reviews: Computational Molecular Science `_ -Geistes-und Sozialwissenschaften --------------------------------- +Human and social sciences +------------------------- * `Digital Humanities Quarterly `_ @@ -94,8 +94,8 @@ Geistes-und Sozialwissenschaften * `Journal of Economic Dynamics and Control `_ -Ingenieurwesen --------------- +Engineering +----------- * `Advances in Engineering Software `_ @@ -104,8 +104,8 @@ Ingenieurwesen * `Renewable Energy `_ -Informatik, Mathematik und Statistik ------------------------------------- +Computer science, mathematics and statistics +-------------------------------------------- * `ACM Transactions on Mathematical Software `_ @@ -140,8 +140,8 @@ Informatik, Mathematik und Statistik `_ * `The Stata Journal `_ -Physik und Geowissenschaften ----------------------------- +Physics and Earth Sciences +-------------------------- * `AAS: The Astronomy Journal `_ * `AAS: The Astrophysical Journal `_ diff --git a/docs/productive/testing/hypothesis.rst b/docs/productive/testing/hypothesis.rst index 723449bc..05cc476f 100644 --- a/docs/productive/testing/hypothesis.rst +++ b/docs/productive/testing/hypothesis.rst @@ -1,18 +1,17 @@ Hypothesis ========== -`Hypothesis `_ ist eine Bibliothek, mit der -ihr Tests schreiben könnt, die anhand einer Quelle von Beispielen -parametrisiert werden. Anschließend werden einfache und nachvollziehbare -Beispiele generiert, anhand derer eure Tests fehlschlagen können und ihr mit -geringen Aufwänden Fehler finden könnt. +`Hypothesis `_ is a library that allows you +to write tests that are parameterised from a source of examples. Then simple and +comprehensible examples are generated, which can be used to fail your tests and +to find errors with little effort. -Beispiel --------- +Example +------- -Zum Testen von Listen mit Fließkommazahlen werden viele Beispiele ausprobiert, -jedoch im Report nur ein einfaches Beispiel für jeden Bug (eindeutiger -*exception type* und Position) angegeben: +To test lists with floating point numbers, many examples are tried, but only a +simple example is given in the report for each bug (unique exception type and +position): .. code-block:: python @@ -53,9 +52,9 @@ jedoch im Report nur ein einfaches Beispiel für jeden Bug (eindeutiger Falsifying example: test_mean(ls=[8.988465674311579e+307, 8.98846567431158e+307]) =========================== 1 failed in 0.11 seconds =========================== -In unserem Beispiel haben wir :doc:`pytest ` den Test finden und -ausführen lassen. Wir hätten jedoch auch explizit einen -:class:`python:unittest.TestCase` definieren können: +In our example we let :doc:`pytest ` find the test and run it. +However, we could also have :defined class:`python:unittest.TestCase` +explicitly: .. code-block:: python @@ -79,17 +78,16 @@ Installation $ pipenv install hypothesis -Alternativ kann Hypothesis auch mit `Erweiterungen -`_ installiert werden, -z.B.: +Alternatively, Hypothesis can also be installed with `extras +`_, e.g. .. code-block:: console $ pipenv install hypothesis[numpy,pandas] .. note:: - Falls ihr pipenv noch nicht installiert hab, findet ihr eine Anleitung hierzu - unter :doc:`/first-steps/install`. + If you haven’t installed pipenv yet, you can find instructions on how to do + this in :doc:`/first-steps/install`. .. seealso:: `Hypothesis for the Scientific Stack diff --git a/docs/productive/testing/index.rst b/docs/productive/testing/index.rst index d8e11aad..a4947c76 100644 --- a/docs/productive/testing/index.rst +++ b/docs/productive/testing/index.rst @@ -1,26 +1,26 @@ -Testen -====== +Testing +======= .. seealso:: * `Python Testing and Continuous Integration `_ -Konzepte +Concepts -------- .. glossary:: Test Case (Testfall) - testet eine einzelnes Szenario. + tests a single scenario. Test Fixture (Prüfvorrichtung) - ist eine konsistente Testumgebung. + is a consistent test environment. Test Suite - ist eine Sammlung mehrerer Test Cases. + is a collection of several test cases. Test Runner - durchläuft eine Test Suite und stellt die Ergebnisse dar. + runs through a test suite and presents the results. Notebooks --------- diff --git a/docs/productive/testing/ipytest.ipynb b/docs/productive/testing/ipytest.ipynb index 8af8ee39..0c43d542 100644 --- a/docs/productive/testing/ipytest.ipynb +++ b/docs/productive/testing/ipytest.ipynb @@ -67,7 +67,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`[clean]` löscht alle zuvor gelaufenen Tests, d.h. es werden nur die in der aktuellen Zelle definierten Tests ausgeführt." + "`[clean]` deletes all previously run tests, ie only the tests defined in the current cell are executed." ] }, { @@ -129,7 +129,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Testparametrisierung" + "## Test parameterisation" ] }, { @@ -168,67 +168,67 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Referenz\n", + "## Reference\n", "\n", "### `%%run_pytest …`\n", "\n", - "IPython-Magic, die zuerst die Zelle und dann `run_pytest` ausführt. In der Zelle übergebene Argumente werden direkt an pytest weitergeleitet. Zuvor sollten mit `import ipytest.magics` die Magics importiert worden sein.\n", + "IPython magic that executes first the cell and then `run_pytest`. Arguments passed in the cell are passed directly to pytest. The Magics should have been imported with `import ipytest.magics` beforehand. \n", "\n", "### `ipytest.run_pytest(module=None, filename=None, pytest_options=(), pytest_plugins=())`\n", "\n", - "führt die Tests im bestehenden Modul (standardmäßig `main`) mit pytest aus.\n", + "runs the tests in the existing module (by default `main`) with pytest.\n", "\n", - "Argumente:\n", + "Arguments:\n", "\n", - "* `module`: das Modul, das die Tests enthält. Wenn nicht angegeben wird, wird `__main__` verwendet.\n", - "* `filename`: Dateiname der Datei, die die Tests enthält. Wenn nichts angegeben wird, wird das `__file__`-Attribut des übergebenen Moduls verwendet.\n", - "* `pytest_options`: zusätzliche Optionen, die an pytest übergeben werden\n", - "* `pytest_plugins`: zusätzliche pytest-Plugins\n", + "* `module`: the module that contains the tests. If not specified, `__main__` is used.\n", + "* `filename`: Filename of the file containing the tests. If nothing is specified, the `__file__`attribute of the passed module is used.\n", + "* `pytest_options`: additional options passed to pytest.\n", + "* `pytest_plugins`: additional pytest plugins.\n", "\n", "### `ipytest.run_tests(doctest=False, items=None)`\n", "\n", - "Argumente:\n", + "Arguments:\n", "\n", - "* `doctest`: Wenn als Wert `True` angegeben wird, wird nach Doctests gesucht.\n", - "* `items`: Das *globals*-Objekt, das die Tests enthält. Wenn `None` angegeben wird, wird das *globals*-Objekt aus dem Call Stack ermittelt.\n", + "* `doctest`: If `True` is specified, angegeben wird, then doctests are searched for.\n", + "* `items`: The *globals* object that contains the tests. If `None` is specified, the *globals* object is obtained from the call stack.\n", "\n", "### `ipytest.clean_tests(pattern=\"test*\", items=None)`\n", "\n", - "löscht diejenigen Tests, deren Namen dem angegebenen Muster entsprechen.\n", + "deletes those tests whose names match the specified pattern.\n", "\n", - "In IPython werden die Ergebnisse aller Auswertungen in globalen Variablen gespeichert, sofern sie nicht explizit gelöscht werden. Dieses Verhalten impliziert, dass beim Umbenennen von Tests die vorherigen Definitionen weiterhin gefunden werden, wenn sie nicht gelöscht werden. Diese Methode zielt darauf ab, diesen Prozess zu vereinfachen.\n", + "In IPython, the results of all evaluations are saved in global variables, unless they are explicitly deleted. This behavior implies that if tests are renamed, the previous definitions will still be found if they are not deleted. This method aims to simplify this process.\n", "\n", - "Ein effektive Methode besteht darin, mit `clean_tests` eine Zelle zu beginnen, dann alle Testfälle zu definieren und schließlich `run_tests` aufzurufen. Auf diese Weise funktioniert das Umbenennen von Tests wie erwartet.\n", + "An effective method is `clean_tests`to start with a cell, then define all test cases and finally `run_tests` call them. That way, renaming tests works as expected.\n", "\n", - "Argumente:\n", + "Arguments:\n", "\n", - "* `pattern`: Ein glob-Pattern, das verwendet wird, um die zu löschenden Tests zu finden.\n", - "* `items`: Das *globals*-Objekt, das die Tests enthält. Wenn `None` angegeben wird, wird das *globals*-Objekt aus dem Call Stack ermittelt.\n", + "* `pattern`: A glob pattern that is used to find the tests to delete.\n", + "* `items`: The *globals* object that contains the tests. If `None` is specified, the globals object is obtained from the call stack.\n", "\n", "### `ipytest.collect_tests(doctest=False, items=None)`\n", "\n", - "sammelt alle Testfälle und sendet sie an `unittest.TestSuite`.\n", + "collects all test cases and sends them to `unittest.TestSuite`.\n", "\n", - "Die Argumente sind die gleichen wie für `ipytest.run_tests`.\n", + "The arguments are the same as for `ipytest.run_tests`.\n", "\n", "### `ipytest.assert_equals(a, b, *args, **kwargs)`\n", "\n", - "vergleicht zwei Objekte und wirft eine *Exception*, wenn sie nicht gleich sind.\n", + "compares two objects and throws an exception if they are not the same.\n", "\n", - "Die Methode `ipytest.get_assert_function` bestimmt die zu verwendende Assert-Implementierung in Abhängigkeit von den folgenden Argumenten:\n", + "The method `ipytest.get_assert_function` determines the assert implementation to be used depending on the following arguments:\n", "\n", - "* `a, b`: die zwei zu vergleichenden Objekte.\n", - "* `args, kwargs`: (Schlüsselwort)-Argumente, die an die zugrundeliegende Testfunktion übergeben werden.\n", + "* `a, b`: the two objects to be compared.\n", + "* `args, kwargs`: (Keyword) arguments that are passed to the underlying test function.\n", "\n", "### `ipytest.get_assert_function(a, b)`\n", "\n", - "bestimmt die zu verwendende Assert-Funktion in Abhängigkeit von den Argumenten.\n", + "determines the assert function to be used depending on the arguments.\n", "\n", - "Wenn eines der Objekte `numpy.ndarray`, `pandas.Series`, `pandas.DataFrame` oder `pandas.Panel` ist, werden die von `numpy` und `pandas` bereitgestellten Assert-Funktionen zurückgegeben.\n", + "If one of the objects is `numpy.ndarray`, `pandas.Series`, `pandas.DataFrame` or `pandas.Panel` the assert functions provided by `numpy` and `pandas` will bei returned.\n", "\n", "### `ipytest.unittest_assert_equals(a, b)`\n", "\n", - "vergleicht zwei Objekte mit der `assertEqual`-Methode von `unittest.TestCase`.\n" + "compares two objects using the `assertEqual` method of `unittest.TestCase`." ] } ], diff --git a/docs/productive/testing/mock.rst b/docs/productive/testing/mock.rst index 605b435f..775c2673 100644 --- a/docs/productive/testing/mock.rst +++ b/docs/productive/testing/mock.rst @@ -1,17 +1,17 @@ Mock ==== -:mod:`unittest.mock` ist eine Python-Testbibliothek. Ab Python 3.3 ist sie in -der Python-Standardbibliothek verfügbar. +:mod:`unittest.mock` is a Python test library. As of Python 3.3, it is available +in the Python standard library. -Beispiel --------- +Example +------- -Es ermöglicht euch, Teile eurer zu testenden Anwendung durch `Mock-Objekte -`_ zu testen und *Assertions* -darüber zu treffen, wie diese verwendet wurden. +It allows you to test parts of your application with `mock objects +`_ and make assertions about how they +have been used. -Zum Beispiel könnt ihr einen Monkeypatch für eine Methode ausführen: +For example, you can do a monkey patch for a method: .. code-block:: python @@ -22,10 +22,9 @@ Zum Beispiel könnt ihr einen Monkeypatch für eine Methode ausführen: thing.method.assert_called_with(3, 4, 5, key='value') -Um Mock-Klassen oder- Objekte in einem zu testenden Modul zu erzeugen, kann der -``patch``-Dekorator verwendet werden. Im folgenden Beispiel wird ein externes -Suchsystem durch eine Mock-Klasse ersetzt, die immer das gleiche Ergebnis -liefert: +The ``patch`` decorator can be used to create mock classes or objects in a +module under test. In the following example, an external search system is +replaced by a mock class that always delivers the same result: .. code-block:: python @@ -39,24 +38,24 @@ liefert: def test_new_watchlist_activities(self): self.assertEqual(len(myapp.get_search_results(q="fish")), 3) -``SearchForm`` bezieht sich hier auf die importierte Klassenreferenz in -``myapp``, nicht auf die ``SearchForm``-Klasse selbst. +``SearchForm`` refers here to the imported class reference in ``myapp``, not to +the ``SearchForm`` class itself. -``get_search_results`` führt eine Suche durch und iteriert über das Ergebnis. +``get_search_results`` performs a search and iterates over the result. Installation ------------ -Für ältere Python-Versionen kann sie installiert werden mit +For older Python versions it can be installed with .. code-block:: console $ pipenv install mock .. note:: - Falls ihr pipenv noch nicht installiert hab, findet ihr eine Anleitung hierzu - unter :doc:`/first-steps/install`. + If you haven’t installed pipenv yet, you can find instructions on how to do + this in :doc:`/first-steps/install`. .. seealso:: - Mit `responses `_ könnt Ihr - Mock-Objekte für die :doc:`/data-rw/requests/index`-Bibliothek erstellen. + With `responses `_ you can create + mock objects for the :doc:`/data-rw/requests/index` library. diff --git a/docs/productive/testing/tox.rst b/docs/productive/testing/tox.rst index 275c73a0..e5bce6f0 100644 --- a/docs/productive/testing/tox.rst +++ b/docs/productive/testing/tox.rst @@ -1,17 +1,16 @@ tox === -`tox `_ ist ein Tool zur Automatisierung des -``virtualenv``-Environment-Management und zum Testen mit mehreren -Interpreter-Konfigurationen. +`tox `_ is a tool for automating ``virtualenv`` +environment management and testing with multiple interpreter configurations. -Mit ``tox`` könnt ihr komplexe Multiparameter-Testmatrizen über eine einfache -Konfigurationsdatei im ``INI``-Stil konfigurieren. +With ``tox`` you can configure complex multi-parameter test matrices via a +simple configuration file in the ``INI`` style. -Beispiel --------- +Example +------- -Erstellt eine ``tox.ini``-Datei: +Creates a ``tox.ini`` file: .. code-block:: ini @@ -23,23 +22,22 @@ Erstellt eine ``tox.ini``-Datei: commands = pytest -Beim Aufrufen von ``pipenv run tox`` werden dann die folgenden Schritte -durchlaufen: +When you call ``pipenv run tox``, the following steps are performed: -#. Optional erstellen eines Python-Package mit +#. Optionally create a Python package with .. code-block:: console $ pipenv run python setup.py sdist -#. Erstellen der in ``envlist`` angegebenen Umgebungen +#. Create the environments specified in ``envlist`` - In jeder dieser Umgebungen werden dann + In each of these environments, then - #. die Abhängigkeiten und Pakete installiert - #. die Befehle aus ``commands`` ausgeführt + #. the dependencies and packages are installed + #. the commands specified in ``commands`` are executed -#. Erstellen eines Reports mit den Ergebnissen aus jeder der Umgebungen, z.B.: +#. Create a report with the results from each of the environments, e.g. .. code-block:: text @@ -55,10 +53,10 @@ Installation $ pipenv install tox .. note:: - Falls ihr pipenv noch nicht installiert hab, findet ihr eine Anleitung hierzu - unter :doc:`/first-steps/install`. + If you haven't installed pipenv yet, you can find instructions on how to do + this in unter :doc:`/first-steps/install`. .. seealso:: - * `Beispiele `_ + * `Examples `_ * `Plugins `_ diff --git a/docs/productive/testing/unittest.ipynb b/docs/productive/testing/unittest.ipynb index 50d0c524..45b0b10b 100755 --- a/docs/productive/testing/unittest.ipynb +++ b/docs/productive/testing/unittest.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Unittests" + "# Unit tests" ] }, { @@ -71,13 +71,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ kann auch [ipython-unittest](https://github.com/JoaoFelipe/ipython-unittest) verwendet werden. Dies ermöglicht die Verwendung der folgenden *Cell Magics* in iPython:\n", + "Alternatively, [ipython-unittest](https://github.com/JoaoFelipe/ipython-unittest) can also be used. This enables the following *Cell Magics* to be used in iPython:\n", "\n", - "* ```%%unittest_main``` führt Testfälle aus, die in einer Zelle definiert sind\n", - "* ```%%unittest_testcase``` erstellt einen Testfall mit der in einer Zelle definierten Funktion und führt ihn aus\n", - "* ```%%unittest```konvertiert Python ```assert``` in Unittest-Funktionen\n", - "* ```%%external``` um externe Unittests durchzuführen\n", - "* ```%%write {mode}``` um externe Dateien zu schreiben" + "* ```%%unittest_main``` executes test cases that are defined in a cell\n", + "* ```%%unittest_testcase``` creates a test case with the function defined in a cell and executes it\n", + "* ```%%unittest```converts Python ```assert``` to unit test functions\n", + "* ```%%external``` to perform external unit tests\n", + "* ```%%write {mode}``` to write external files" ] }, { @@ -282,36 +282,32 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Standardmäßig trennt Docstring in dieser Magie die Unittest-Methoden. Wenn jedoch keine Docstrings verwendet werden, erstellen die *Cell Magics* für jede ```assert```-Methode." + "By default, Docstring separates the unit test methods in this magic. However, if docstrings are not used, the *Cell Magics* create one for each `assert` method." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Diese *Cell Magics* unterstützen optionale Argumente:\n", + "These *Cell Magics* support optional arguments:\n", "\n", - "* ```-p``` (```--previous```) ```P```\n", + "* `-p` (`--previous`) `P`\n", "\n", - " setzt den Cursor auf P Zellen vor (Standardwert: ```-1``` entspricht der nächsten Zelle)\n", + " puts the cursor in front of P cells (default `-1` corresponds to the next cell)\n", "\n", - " Dies funktioniert jedoch nur, wenn auch [jupyter_dojo](https://github.com/JoaoFelipe/jupyter-dojo) installiert ist.\n", + " However, this only works if [jupyter_dojo](https://github.com/JoaoFelipe/jupyter-dojo) is also installed. \n", " \n", - " \n", - "* ```-s``` (```--stream```) ```S```\n", + "* `-s` (`--stream`) `S`\n", "\n", - " legt den *Ooutput-Stream* fest (Standardwert: ```sys.stdout```)\n", - " \n", + " sets the *ooutput stream* (default is: `sys.stdout`)\n", " \n", - "* ```-t``` (```--testcase```) ```T```\n", + "* `-t` (`--testcase`) `T`\n", "\n", - " definiert den Namen des TestCase für ```%%unittest``` und ```%%unittest_testcase```\n", - " \n", + " defines the name of the TestCase for `%%unittest` and `%%unittest_testcase`\n", " \n", - "* ```-u``` (```--unparse```)\n", + "* `-u` (`--unparse`)\n", "\n", - " gibt den Quellcode nach den Transformationen aus\n", - "\n" + " outputs the source code after the transformations" ] }, { diff --git a/docs/productive/testing/unittest2.rst b/docs/productive/testing/unittest2.rst index 0de221d5..39571130 100644 --- a/docs/productive/testing/unittest2.rst +++ b/docs/productive/testing/unittest2.rst @@ -1,16 +1,15 @@ ``unittest2`` ============= -`unittest2 `_ ist ein Backport von -:mod:`unittest`, mit verbesserter API und besseren *Assertions* als in früheren -Python-Versionen. +`unittest2 `_ is a backport of +:mod:`unittest`, with improved API and better assertions than in previous Python +versions. -Beispiel --------- +Example +------- -Möglicherweise wollt ihr das Modul unter dem Namen ``unittest`` importieren um -die Portierung von Code auf neuere Versionen des Moduls in Zukunft zu -vereinfachen: +You may want to import the module under the name ``unittest`` to simplify the +porting of code to newer versions of the module in the future: .. code-block:: python @@ -19,9 +18,9 @@ vereinfachen: class MyTest(unittest.TestCase): ... -Auf diese Weise könnt ihr, wenn ihr zu einer neueren Python-Version wechselt und -das Modul ``unittest2`` nicht mehr benötigt, einfach den Import in eurem -Testmodul ändern, ohne dass ihr weiteren Code ändern müsst. +In this way, if you switch to a newer Python version and no longer need the +module ``unittest2``, you can simply change the import in your test module +without having to change any further code. Installation ------------ @@ -31,5 +30,5 @@ Installation $ pipenv install unittest2 .. note:: - Falls ihr pipenv noch nicht installiert hab, findet ihr eine Anleitung hierzu - unter :doc:`/first-steps/install`. + If you haven’t installed pipenv yet, you can find instructions on how to do + this in :doc:`/first-steps/install`. diff --git a/docs/refactoring/autoqual/black.rst b/docs/refactoring/autoqual/black.rst index 10959943..06f497fa 100644 --- a/docs/refactoring/autoqual/black.rst +++ b/docs/refactoring/autoqual/black.rst @@ -1,8 +1,8 @@ Black ===== -`Black `_ formatiert euren Code in ein schönes -und deterministisches Format. +`Black `_ formats your code in a nice and +deterministic format. .. seealso:: Was lesbaren Code auszeichnet, ist gut beschrieben im Trey Hunners Blog-Post @@ -16,10 +16,10 @@ Installation $ pipenv install black -Überprüfen ----------- +Check +----- -Anschließend könnt ihr die Installation überprüfen mit +Then you can check the installation with .. code-block:: console @@ -28,21 +28,21 @@ Anschließend könnt ihr die Installation überprüfen mit Integration ----------- -Mit `jupyter-black `_ könnt ihr Black -auch bereits in euren Jupyter Notebooks verwenden. +With `jupyter-black `_ you can already +use Black in your Jupyter notebooks. .. seealso:: - Auch die Integration in andere Editoren wie PyCharm, Wing IDE oder Vim ist - möglich, s. `Editor integration + Integration into other editors such as PyCharm, Wing IDE or Vim is also + possible, see `Editor integration `_ -Konfiguration +Configuration ------------- -Im Gegensatz zur Standardformatierung von Black -mit 88 Zeichen bevorzuge ich jedoch eine Zeilenlänge von 79 Zeichen. +In contrast to Black’s standard 88-character formatting, however, I prefer a +line length of 79 characters. -Hierfür könnt ihr in ``pyproject.toml`` folgendes eintragen: +For this you can enter the following in ``pyproject.toml``: .. code-block:: toml @@ -50,6 +50,6 @@ Hierfür könnt ihr in ``pyproject.toml`` folgendes eintragen: line-length = 79 .. seealso:: - Weitere Informationen zur Konfiguration von Black in der Toml-Datei erhaltet - ihr in `pyproject.toml + You can get more information about the configuration of Black in the Toml + file in `pyproject.toml `_. diff --git a/docs/refactoring/autoqual/flake8.rst b/docs/refactoring/autoqual/flake8.rst index 63755a70..d03aff51 100644 --- a/docs/refactoring/autoqual/flake8.rst +++ b/docs/refactoring/autoqual/flake8.rst @@ -1,10 +1,10 @@ ``flake8`` ========== -`flake8 `_ stellt sicher, dass euer Code -größtenteils `PEP 8 `_ folgt. Eine -automatische Formattierung, z.B. mit :doc:`black`, ist jedoch noch komfortabler. -Zudem prüft ``flake8`` auf nicht verwendete Importe. +`flake8 `_ ensures that most of your code +follows `PEP 8 `_. However, automatic +formatting, for example with :doc:`black`, is even more convenient. In addition +``flake8`` also checks for unused imports. Installation ------------ @@ -14,18 +14,18 @@ Installation $ spack env activate python-374 $ spack install py-flake8 ^python@3.7.4 -Überprüfen ----------- +Check +----- .. code-block:: console $ flake8 path/to/your/code -Konfiguration +Configuration ------------- -``flake8`` kann für :doc:`/productive/testing/tox` konfiguriert werden in der -``tox.ini``-Dateie eines Pakets, z.B.: +``flake8`` can be configured for :doc:`/productive/testing/tox` in the +``tox.ini`` file of a package, e.g.: .. code-block:: ini diff --git a/docs/refactoring/autoqual/index.rst b/docs/refactoring/autoqual/index.rst index 13c3f4c4..8e726809 100644 --- a/docs/refactoring/autoqual/index.rst +++ b/docs/refactoring/autoqual/index.rst @@ -1,10 +1,10 @@ -Automatisieren der Code-Qualität -================================ +Automating code quality +======================= -Im Folgenden möchte ich einige Werkzeuge und Konzepte vorstellen, die die -Wartung und Pflege von Python-Paketen und anderem Quellcode vereinfachen. -Zusammen mit :doc:`/productive/git/pre-commit` läßt sich mit ihnen die -Code-Qualität automatisiert überprüfen und verbessern. +In the following I would like to introduce some tools and concepts that simplify +the maintenance of Python packages and other source code. Together with +:doc:`/productive/git/pre-commit`, they can be used to automatically check and +improve the code quality. Checker ------- diff --git a/docs/refactoring/autoqual/isort.rst b/docs/refactoring/autoqual/isort.rst index c46165e2..fdae1fdc 100644 --- a/docs/refactoring/autoqual/isort.rst +++ b/docs/refactoring/autoqual/isort.rst @@ -1,8 +1,8 @@ ``isort`` ========= -`isort `_ formatiert eure -``import``-Anweisungen in getrennte und sortierte Blöcke. +`isort `_ formats your ``import`` +statements in separate and sorted blocks. Installation ------------ @@ -11,10 +11,10 @@ Installation $ pipenv install isort -Konfiguration +Configuration ------------- -``isort`` lässt sich z.B. in der ``pyproject.toml``-Datei konfigurieren: +``isort`` can be configured e.g. in the ``pyproject.toml`` file: .. code-block:: ini @@ -31,14 +31,14 @@ Konfiguration known_first_party="jupyter-tutorial" known_third_party=["mpi4py", "numpy", "requests"] -Um Pakete von Drittanbietern gegenüber Euren Projektimporten zu erkennen, könnt -ihr entweder Euer Projekt zusammen mit ``isort`` installieren oder -`seed-isort-config `_ verwenden. +In order to recognise third-party packages for your project imports, you can +either install your project together with ``isort`` or use `seed-isort-config +`_. .. note:: - Mit isort 5 könnt Ihr Profile verwenden. Dies erleichtert die Konfiguration - von isort, um auch zukünftig mit :doc:`black` zusammenzuspielen: - + With isort 5 you can use profiles. This simplifies the configuration of + isort in order to continue to play with :doc:`black` in the future: + .. code-block:: ini isort --profile black . diff --git a/docs/refactoring/autoqual/manifest.rst b/docs/refactoring/autoqual/manifest.rst index d21a5f4f..d167e805 100644 --- a/docs/refactoring/autoqual/manifest.rst +++ b/docs/refactoring/autoqual/manifest.rst @@ -1,9 +1,9 @@ ``check-manifest`` ================== -`check-manifest `_ ist ein Werkzeug, mit dem -ihr schnell überprüfen könnt, ob die Datei ``Manifest.in`` für Pyton-Pakete -vollständig ist. +`check-manifest `_ is a tool with which you +can quickly check whether the file ``Manifest.in`` for Pyton packages is +complete. Installation ------------ @@ -12,15 +12,15 @@ Installation $ pipenv install check-manifest -Überprüfen ----------- +Check +----- .. code-block:: console $ cd /path/to/MANIFEST.in $ pipenv run check-manifest -oder für eine automatische Aktualisierung +… or for an automatic update .. code-block:: console @@ -43,13 +43,13 @@ oder für eine automatische Aktualisierung include *.py include tox.ini -Konfiguration +Configuration ------------- -Ihr könnt ``check-manifest`` so konfigurieren, dass bestimmte Dateimuster -ignoriert werden, indem ihr einen Abschnitt ``[tool.check-manifest]`` in eurer -``pyproject.toml``-Datei oder einen Abschnitt ``[check-manifest]`` in eurer -``setup.cfg`` oder ``tox.ini``-Datei anlegt, z.B.: +You can configure ``check-manifest`` so that certain file patterns are ignored +by creating a section ``[tool.check-manifest]`` in your ``pyproject.toml`` +file or a section ``[check-manifest]`` in your ``setup.cfg`` or ``tox.ini`` +file, for example: .. code-block:: yaml @@ -61,13 +61,12 @@ ignoriert werden, indem ihr einen Abschnitt ``[tool.check-manifest]`` in eurer ignore = .travis.yml -``check-manifest`` kennt die folgenden Optionen: +``check-manifest`` knows the following options: ``ignore`` - Eine Liste von Dateinamenmustern, die von ``check-manifest`` ignoriert - werden. Verwendet diese Option, wenn ihr Dateien in eurem - Versionskontrollsystem behalten möchtet, die nicht in eurem - Quelldistributionen enthalten sein sollen. Die Standardliste ist: + A list of filename patterns that are ignored by ``check-manifest``. Use this + option if you want to keep files in your version control system that + shouldn’t be in your source distributions. The standard list is: .. code-block:: @@ -87,20 +86,18 @@ ignoriert werden, indem ihr einen Abschnitt ``[tool.check-manifest]`` in eurer * .mo ``ignore-default-rules`` - wenn ``true``, dann ersetzen deine ``ignore``-Angaben die Standardliste, - anstatt sie zu ergänzen. + If ``true``, your ``ignore`` entries replace the standard list instead of + completing it. ``ignore-bad-ideas`` - Eine Liste von Dateinamenmustern, de von der Prüfung der generierten Dateien - ignoriert werden. Damit könnt ihr generierte Dateien in eurem - Versionskontrollsystem behalten, auch wenn dies üblicherweise eine schlechte - Idee ist. + A list of filename patterns that will be ignored by checking the generated + files. This allows you to keep generated files in your version control + system, even if this is usually a bad idea. -Integration in die Versionskontrolle ------------------------------------- +Integration with version control +-------------------------------- -Mit :doc:`/productive/git/pre-commit` kann `check-manifest` Teil eures -Git-Workflows sein. Fügt hierfür eurer `.pre-commit-config.yaml`-Datei folgendes -hinzu: +With :doc:`/productive/git/pre-commit`, `check-manifest` can be part of your Git +workflow. To do this, add the following to your `.pre-commit-config.yaml` file: .. code-block:: yaml diff --git a/docs/refactoring/autoqual/mypy.rst b/docs/refactoring/autoqual/mypy.rst index e03dc566..b54951c1 100644 --- a/docs/refactoring/autoqual/mypy.rst +++ b/docs/refactoring/autoqual/mypy.rst @@ -1,30 +1,29 @@ Mypy ==== -Mit `Mypy `_ könnt ihr eine statische Typüberprüfung -vornehmen. +With `Mypy `_ you can do a static type check. Installation ------------ -Mypy erfordert Python≥3.5. Dann kann es installiert werden, z.B. mit: +Mypy requires Python≥3.5. Then it can be installed, e.g. with: .. code-block:: console $ pipenv install mypy -Überprüfen ----------- +Check +----- -Dann könnt ihr es überprüfen, z.B. mit: +Then you can check it, e.g. with: .. code-block:: console $ pipenv run mypy myprogram.py .. note:: - Obwohl Mypy mit Python3 installiert werden muss, kann es auch Python2-Code - analysieren, z.B. mit: + Although Mypy needs to be installed with Python3, it can also parse Python2 + code, e.g. with: .. code-block:: console diff --git a/docs/refactoring/autoqual/prettier.rst b/docs/refactoring/autoqual/prettier.rst index d5860b72..628e07c3 100644 --- a/docs/refactoring/autoqual/prettier.rst +++ b/docs/refactoring/autoqual/prettier.rst @@ -1,12 +1,12 @@ ``prettier`` ============ -`prettier `_ bietet automatische Formatierer für andere -Dateitypen, u.a. für `TypeScript `_, `JSON +`prettier `_ offers automatic formatters for other file +types, including `TypeScript `_, `JSON `_, `Vue `_, `YAML `_, `TOML `_ -und `XML `_ an. +and `XML `_. Installation ------------ @@ -15,14 +15,14 @@ Installation $ npm install prettier --save-dev --save-exact -Konfiguration --------------- +Configuration +------------- .. code-block:: console $ npx prettier --write path/to/my/file.js -Pre-commit-Hook für ``prettier`` +Pre-commit hook for ``prettier`` -------------------------------- Installation @@ -31,11 +31,10 @@ Installation $ npm install pretty-quick husky --save-dev -Konfiguration +Configuration ~~~~~~~~~~~~~ -In der ``package.json``-Datei kann der Pre-commit-Hook folgendermaßen -konfiguriert werden: +In the ``package.json`` file you can configure the pre-commit hook as follows: .. code-block:: json diff --git a/docs/refactoring/index.rst b/docs/refactoring/index.rst index 3dd6df37..33309ec6 100644 --- a/docs/refactoring/index.rst +++ b/docs/refactoring/index.rst @@ -1,10 +1,10 @@ Refactoring =========== -Unter Refactoring wird die Verbesserung des Quellcodes verstanden, wobei die -Ergebnisse unverändert bleiben sollen. Dabei können die Ziele unterschiedlich -sein: einmal kann der Code lesbarer, wartbarer und besser erweiterbar werden, -um anderen kann jedoch auch die Ausführgeschwindigkeit erhöht werden. +Refactoring is understood to be the improvement of the source code, whereby the +results should remain unchanged. The goals can be different: on the one hand, +the code can become better readable, maintainable and expandable, on the other +hand, the execution speed can also be increased. .. toctree:: :hidden: diff --git a/docs/refactoring/parallel/async-example.ipynb b/docs/refactoring/parallel/async-example.ipynb index f15fa2c6..ab082107 100644 --- a/docs/refactoring/parallel/async-example.ipynb +++ b/docs/refactoring/parallel/async-example.ipynb @@ -4,13 +4,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Async-Beispiel\n", + "# Async example\n", "\n", - "Hierbei sind folgende Fragen zu beantworten:\n", + "The following questions have to be answered:\n", "\n", - "1. Wie kann die Geschäftslogik in Callbacks isoliert werden?\n", - "2. Wie kann die Callback-Logik linear mit Generatoren geschrieben werden?\n", - "3. Wie können zeitgesteuerte Events geplant werden?" + "1. How can the business logic in callbacks be isolated?\n", + "2. How can the callback logic be written linearly with generators?\n", + "3. How can time-controlled events be planned?" ] }, { diff --git a/docs/refactoring/parallel/index.rst b/docs/refactoring/parallel/index.rst index 4dc106ca..0b4ed57f 100644 --- a/docs/refactoring/parallel/index.rst +++ b/docs/refactoring/parallel/index.rst @@ -1,10 +1,10 @@ -Ausführung parallelisieren -========================== +Parallelise execution +===================== -Anhand von drei Beispielen zu :doc:`Threading `, -:doc:`Multiprocessing ` und :doc:`Async -` werden die Regeln und Best Practices bei der Nutzung von -Parallelisierung veranschaulicht. + +Three examples of :doc:`Threading `, :doc:`Multiprocessing +` and :doc:`Async ` illustrate the rules and +best practices for using parallelisation. .. toctree:: :hidden: diff --git a/docs/refactoring/parallel/introduction.ipynb b/docs/refactoring/parallel/introduction.ipynb index 59f46ab1..b2b1b0ba 100644 --- a/docs/refactoring/parallel/introduction.ipynb +++ b/docs/refactoring/parallel/introduction.ipynb @@ -4,22 +4,22 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Einführung in die Parallelisierung" + "# Introduction to parallelisation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Martelli’s Modell der Skalierbarkeit\n", + "## Martelli’s model of scalability\n", "\n", - "| Anzahl Kerne | Beschreibung |\n", - "| ------------ | -------------------------------------- |\n", - "| 1 | Einzelner Thread und einzelner Prozess |\n", - "| 2–8 | Mehrere Threads und mehrere Prozesse |\n", - "| ≥9 | Verteilte Verarbeitung |\n", + "| Number of cores | Description |\n", + "| ---------------- | -------------------------------------- |\n", + "| 1 | Single thread and single process |\n", + "| 2–8 | Multiple threads and multiple processes|\n", + "| ≥9 | Distributed processing |\n", "\n", - "Martelli’s Beobachtung: Im Laufe der Zeit wird die zweite Kategorie immer unbedeutender: Einzelne Kerne werden immer leistungsfähiger und große Datensätze immer größer." + "Martelli’s observation: In the course of time, the second category becomes more and more insignificant: individual cores are becoming more and more powerful and large data sets are getting bigger and bigger." ] }, { @@ -28,49 +28,49 @@ "source": [ "## Global Interpreter Lock (GIL)\n", "\n", - "CPython verfügt über eine Sperre für seinen intern geteilten globalen Status. Dies hat zur Folge, dass nicht mehr als ein Thread gleichzeitig laufen kann.\n", + "CPython has a lock on its internally shared global state. As a result, no more than one thread can run at the same time.\n", "\n", - "Für I/O-lastige Anwendungen ist das GIL kein großes Problem; bei CPU-lastigen Anwendungen führt die Verwendung von Threading jedoch zu einer Verlangsamung. Dementsprechend ist Multi-Processing für uns spannend um mehr CPU-Zyklen zu erhalten." + "The GIL is not a big problem for I/O-heavy applications; however, using threading will slow down CPU-heavy applications. Accordingly, multi-processing is exciting for us to get more CPU cycles." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Threads vs. Prozesse vs. Async\n", + "## Threads vs. Processes vs. Async\n", "\n", "### Threads\n", "\n", "#### Pros\n", "\n", - "* Threads haben den Vorteil, einen gemeinsamen Status zu teilen. Allerdings kann dies auch zu *Race Conditions* führen, d.h., die Ergebnisse einer Operation können vom zeitlichen Verhalten bestimmter Einzeloperationen abhängen.\n", + "* Threads have the advantage of sharing a common status. However, this can also lead to race conditions, ie the results of an operation can depend on the timing of certain individual operations.\n", "\n", - "* Threads wechseln präemptiv, s. [Präemptives Multitasking](https://de.wikipedia.org/wiki/Multitasking#Pr%C3%A4emptives_Multitasking). Dies ist praktisch, da Ihr keinen expliziten Code hinzufügen müsst, um einen Wechsel der Tasks zu verursachen.\n", + "* Threads change preemptively, see [Preemptive multitasking](https://en.wikipedia.org/wiki/Computer_multitasking#Preemptive_multitasking). This is useful because you don’t have to add any explicit code to cause the task to switch.\n", "\n", - "* Threading funktioniert normalerweise mit vorhandenem Code und Werkzeugen, solange Locks für kritische Abschnitte hinzugefügt werden.\n", + "* Threading usually works with existing code and tools as long as locks are added to critical sections.\n", "\n", - "* Threads erfordern sehr wenig Tooling: [Lock](https://docs.python.org/3/library/threading.html#threading.Lock) und [Queues](https://docs.python.org/3/library/queue.html).\n", + "* Threads require very little tooling: [Lock](https://docs.python.org/3/library/threading.html#threading.Lock) and [Queues](https://docs.python.org/3/library/queue.html).\n", "\n", "#### Cons\n", "\n", - "* Die Kosten für diese Bequemlichkeit sind, dass ihr davon ausgehen müsst, dass ein solcher Wechsel jederzeit möglich ist. Dementsprechend müssen kritische Bereiche mit Locks geschützt werden.\n", + "* The cost of this convenience is that you have to assume that such a change is possible at any time. Accordingly, critical areas must be protected with locks.\n", "\n", - "* Die Leistungsgrenze für Threads ist eine CPU abzüglich der Kosten für Task-Switches und Synchronisationsaufwände." + "* The performance limit for threads is one CPU minus the costs for task switches and synchronization efforts." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Prozesse\n", + "### Processes\n", "\n", "#### Pros\n", "\n", - "* Die Stärke von Prozessen ist, unabhängig voneinander zu sein.\n", + "* The strength of processes is to be independent of one another.\n", "\n", "#### Cons\n", "\n", - "* Allerdings kommunizieren sie auch nicht miteinander. Daher werden [Interprocess Communication (IPC)](https://docs.python.org/3/library/ipc.html), [object pickling](https://docs.python.org/3/library/pickle.html) und anderer Overhead notwendig." + "* However, they do not communicate with each other either. Therefore, [Interprocess Communication (IPC)](https://docs.python.org/3/library/ipc.html), [object pickling](https://docs.python.org/3/library/pickle.html) and other overheads are necessary." ] }, { @@ -81,14 +81,13 @@ "\n", "#### Pros\n", "\n", - "* Async schaltet kooperativ um, daher müsst ihr explizit [yield](https://docs.python.org/3/reference/simple_stmts.html#yield) oder [await](https://docs.python.org/3/reference/expressions.html#await) hinzufügen, um einen Task-Switch herbeizuführen. Damit könnt ihr kontrollieren, wann diese Task-Switches und ggf. Locks und Synchronisationen stattfinden sollen. Ihr könnt daher die Aufwände für Task-Switches sehr niedrig halten. Zudem hat der Aufruf einer reinen Python-Funktion mehr Overhead als die erneute Anfrage eines *generator* oder *awaitable* – d.h., Async ist sehr billig.\n", - "\n", - "* Async kann die CPU-Auslastung verbessern, da es die üblichen Aufwände reduzieren kann.\n", - "* Bei komplexen Systemen kommt man mit async viel einfacher zum Ziel als mit Threads mit Locks.\n", + "* Async switches cooperatively, so you have to explicitly add [yield](https://docs.python.org/3/reference/simple_stmts.html#yield) or [await](https://docs.python.org/3/reference/expressions.html#await) for a task switch. This allows you to control when these tasks switches and, if necessary, locks and synchronisations should take place. You can therefore keep the effort for task switches very low. In addition, calling a pure Python function has more overhead than requesting a generator or awaitable again –- that is, async is very cheap.\n", + "* Async can improve CPU usage because it can reduce the usual overhead.\n", + "* With complex systems, async is much easier than threads with locks.\n", "\n", "#### Cons\n", "\n", - "* Async benötigt eine große Menge an Werkzeugen: [futures](https://docs.python.org/3/library/asyncio-task.html#future), [Event Loops](https://docs.python.org/3/library/asyncio-eventloops.html) und nicht-blockierende Versionen von fast allem." + "* Async requires a large number of tools: [futures](https://docs.python.org/3/library/asyncio-task.html#future), [Event Loops](https://docs.python.org/3/library/asyncio-eventloops.html), and non-blocking versions of almost everything." ] } ], diff --git a/docs/refactoring/parallel/ipyparallel/asyncresult.ipynb b/docs/refactoring/parallel/ipyparallel/asyncresult.ipynb index 3e4b26ec..0042fbd2 100644 --- a/docs/refactoring/parallel/ipyparallel/asyncresult.ipynb +++ b/docs/refactoring/parallel/ipyparallel/asyncresult.ipynb @@ -4,11 +4,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# `AsyncResult`-Objekt\n", + "# `AsyncResult` object\n", "\n", - "`apply()` gibt im `noblock`-Modus ein `AsyncResult`-Objekt zurück. Dieses erlaubt zu einem späteren Zeitpunkt Anfragen mit der `get()`-Methode zu den Ergebnissen. Überdies werden in diesem Objekt auch bei der Ausführung anfallende Metadaten gesammelt.\n", + "`apply()` returns in the `noblock` mode an `AsyncResult` object. This allows inquiries with the `get()` method at a later point in time. In addition, metadata occurring during execution is also collected in this object.\n", "\n", - "Das [AsyncResult](https://ipyparallel.readthedocs.io/en/latest/details.html#AsyncResult)-Objekt bietet eine Reihe praktischer Funktionen für die Parallelisierung, die über Pythons [multiprocessing.pool.AsyncResult](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.AsyncResult). hinausgehen:" + "The [AsyncResult](https://ipyparallel.readthedocs.io/en/latest/details.html#AsyncResult) object provides a number of useful functions for parallelisation that can be accessed through Python’s [multiprocessing.pool.AsyncResult](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.AsyncResult):" ] }, { @@ -39,7 +39,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Metadaten\n", + "## Metadata\n", "\n", "`Client.metadata`" ] @@ -55,7 +55,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Iterierbare Map-Ergebnisse" + "## Iterable map results" ] }, { @@ -170,11 +170,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "1. `map(sq, X)` berechnet das Quadrat jedes Elements in der Liste.\n", - "2. `reduce(add, sqX) / len(X)` berechnet den Mittelwert indem die Liste von `AsyncMapResult` summiert und durch die Anzahl dividiert wird.\n", - "3. Quadratwurzel der resultierenden Zahl.\n", + "1. `map(sq, X)` computes the square of each item in the list.\n", + "2. `reduce(add, sqX) / len(X)` calculates the mean by adding the list of `AsyncMapResult` and dividing by the number.\n", + "3. Square root of the resulting number.\n", "\n", - "> **Siehe auch:** Wenn ihr die Ergebnisse von `AsyncResult` oder `AsyncMapResult` noch erweitern wollt, könnt ihr dies mit dem `msg_ids`-Attribut. Ein Beispiel hierfür findet ihr unter [ipyparallel/examples/customresults.py](https://github.com/ipython/ipyparallel/blob/master/examples/customresults.py)." + "> **See also:** If you want to expand the results of `AsyncResult` or `AsyncMapResult` you can do so with the `msg_ids` attribute. You can find an example for this at [ipyparallel/examples/customresults.py](https://github.com/ipython/ipyparallel/blob/master/examples/customresults.py)." ] } ], diff --git a/docs/refactoring/parallel/ipyparallel/check.ipynb b/docs/refactoring/parallel/ipyparallel/check.ipynb index 2fdebd21..ae1a2f03 100644 --- a/docs/refactoring/parallel/ipyparallel/check.ipynb +++ b/docs/refactoring/parallel/ipyparallel/check.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Überprüfen der Installation" + "# Check the installation" ] }, { diff --git a/docs/refactoring/parallel/ipyparallel/config.rst b/docs/refactoring/parallel/ipyparallel/config.rst index 2b4e7180..e5a61901 100644 --- a/docs/refactoring/parallel/ipyparallel/config.rst +++ b/docs/refactoring/parallel/ipyparallel/config.rst @@ -1,12 +1,12 @@ -Konfiguration +Configuration ============= -Für die Konfiguration wird beim Starten des IPython-Hub für Client und Engine jeweils eine -Konfigurationsdatei angelegt, üblicherweise in +For the configuration, a configuration file is created for the client and engine +when the IPython hub is started, usually in ``~/.ipython/profile_default/security/``. -#. Falls wir nicht das ``default``-Profil verwenden wollen, sollten wir zunächst ein neues - IPython-Profil erstellen mit: +#. If we don’t want to use the ``default`` profile, we should first create a new + IPython profile with: .. code-block:: console @@ -18,15 +18,16 @@ Konfigurationsdatei angelegt, üblicherweise in [ProfileCreate] Generating default config file: '/Users/veit/.ipython/profile_parallel/ipcluster_config.py ``--parallel`` - schließt die Konfigurationsdateien für *Parallel Computing* (``ipengine``, ``ipcontroller`` etc.) ein. + includes the configuration files for *Parallel Computing* (``ipengine``, ``ipcontroller`` etc.). -#. Beim Starten des IPython-Controller und der -Engines werden die Dateien ``ipcontroller-engine.json`` und - ``ipcontroller-client.json`` dann in ``~/.ipython/profile_default/security/`` erzeugt. +#. When the IPython controller and the engines are started, the files + ``ipcontroller-engine.json`` and ``ipcontroller-client.json`` are generated + in ``~/.ipython/profile_default/security/``. -``ipcluster`` in ``mpiexec``/``mpirun``-Modus ---------------------------------------------- +``ipcluster`` in ``mpiexec``/``mpirun`` mode +-------------------------------------------- -#. Erstellen des Profils: +#. Creating the profile:: .. code-block:: console @@ -37,15 +38,15 @@ Konfigurationsdatei angelegt, üblicherweise in [ProfileCreate] Generating default config file: '/Users/veit/.ipython/profile_mpi/ipengine_config.py' [ProfileCreate] Generating default config file: '/Users/veit/.ipython/profile_mpi/ipcluster_config.py' -#. Editieren von ``ipcluster_config.py``: +#. Editing of ``ipcluster_config.py``: - #. Damit die MPI-Launcher verwendet werden: + #. so that the MPI launcher can be used: .. code-block:: python c.IPClusterEngines.engine_launcher_class = 'MPIEngineSetLauncher' -#. Anschließend kann der Cluster gestartet werden mit: +#. The cluster can then be started with: .. code-block:: console diff --git a/docs/refactoring/parallel/ipyparallel/direct.ipynb b/docs/refactoring/parallel/ipyparallel/direct.ipynb index 29de5576..932ffa2d 100644 --- a/docs/refactoring/parallel/ipyparallel/direct.ipynb +++ b/docs/refactoring/parallel/ipyparallel/direct.ipynb @@ -4,14 +4,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# IPython’s `Direct`-Interface" + "# IPython’s `Direct` interface" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Erstellen eines `DirectView`" + "## Create a `DirectView`" ] }, { @@ -57,7 +57,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Verwenden aller *Engines*:" + "Use all engines:" ] }, { @@ -73,11 +73,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## `map()`-Funktion\n", + "## `map()` function\n", "\n", - "Python’s builtin `map()`-Funktion kann auf eine Sequenz von Elementen angewendet werden und üblicherweise einfach zu parallelisieren. \n", + "Python’s builtin `map()` function can be applied to a sequence of elements and is usually easy to parallelise.\n", "\n", - "Beachtet bitte, dass die `DirectView`-Version von `map()` kein automatisches Load-Balancing macht. Hierfür müsst ihr ggf. `LoadBalancedView` verwenden." + "Please note that the `DirectView` version of `map()` does not do automatic load balancing. You may have to use `LoadBalancedView` for this." ] }, { diff --git a/docs/refactoring/parallel/ipyparallel/index.rst b/docs/refactoring/parallel/ipyparallel/index.rst index f6b7ce32..6fca6a52 100644 --- a/docs/refactoring/parallel/ipyparallel/index.rst +++ b/docs/refactoring/parallel/ipyparallel/index.rst @@ -1,13 +1,9 @@ ``ipyparallel`` =============== -Dieser Abschnitt gibt einen Überblick über `ipyparallel -`_, das verschiedene Arten von -Parallelisierung unterstützt, u.a.: - -- Single Program, Multiple Data (SPMD) -- Multiple program, multiple data (MPMD) -- Message Passing Interface (MPI) +This section provides an overview of `ipyparallel +` which supports different types of +parallelisation, including: .. toctree:: :hidden: diff --git a/docs/refactoring/parallel/ipyparallel/install.rst b/docs/refactoring/parallel/ipyparallel/install.rst index 4346c4a4..c9e3699a 100644 --- a/docs/refactoring/parallel/ipyparallel/install.rst +++ b/docs/refactoring/parallel/ipyparallel/install.rst @@ -7,7 +7,7 @@ Installation $ pipenv install ipython[all] -#. Notebook-Server-Extension aktivieren: +#. Activate notebook server extension: .. code-block:: console @@ -17,7 +17,7 @@ Installation - Validating... ipyparallel.nbextension OK -#. Notebook-Extension installieren: +#. Install notebook extension: .. code-block:: console @@ -29,7 +29,7 @@ Installation jupyter nbextension enable ipyparallel --py -#. Notebook-Extension aktivieren: +#. Activate notebook extension: .. code-block:: console diff --git a/docs/refactoring/parallel/ipyparallel/intro.rst b/docs/refactoring/parallel/ipyparallel/intro.rst index 4c82fb8a..5a524fcf 100644 --- a/docs/refactoring/parallel/ipyparallel/intro.rst +++ b/docs/refactoring/parallel/ipyparallel/intro.rst @@ -1,10 +1,10 @@ -Überblick -========= +Overview +======== -Architektur ------------ +Architecture +------------ -Die ``IPython.parallel``-Architektur besteht aus vier Komponenten: +The ``IPython.parallel`` architecture consists of four components: .. graphviz:: @@ -40,41 +40,40 @@ Die ``IPython.parallel``-Architektur besteht aus vier Komponenten: IPython-Engine ~~~~~~~~~~~~~~ -Die IPython-Engine ist eine Erweiterung des IPython-Kernels für Jupyter. Das -Modul wartet auf Anfragen aus dem Netzwerk, führt Code aus und gibt die -Ergebnisse zurück. IPython parallel erweitert das Jupyter-Messaging-Protokoll um -native Python-Objektserialisierung und fügt einige zusätzliche Befehle hinzu. -Zum parallelen und verteilten Rechnen werden mehrere Engines gestartet. +The IPython engine is an extension of the IPython kernel for Jupyter. The module +waits for requests from the network, executes code and returns the results. +IPython parallel extends the Jupyter messaging protocol with native Python +object serialisation and adds some additional commands. Several engines are +started for parallel and distributed computing. IPython-Hub ~~~~~~~~~~~ -Die Hauptaufgabe des Hubs besteht darin, Verbindungen zu Clients und Engines -herzustellen und zu überwachen. +The main job of the hub is to establish and monitor connections to clients and +engines. IPython-Schedulers ~~~~~~~~~~~~~~~~~~ -Alle Aktionen, die an der Engine ausgeführt werden können, durchlaufen einen -Scheduler. Während die Engines selbst blockieren, wenn Benutzercode ausgeführt -wird, verbergen die Scheduler dies vor dem Benutzer, um eine vollständig -asynchrone Schnittstelle für eine Reihe von Engines bereitzustellen. +All actions that can be carried out on the engine go through a scheduler. While +the engines themselves block when user code is executed, the schedulers hide +this from the user to provide a fully asynchronous interface for a number of +engines. IPython-Client ~~~~~~~~~~~~~~ -Es gibt ein Hauptobjekt ``Client`` um eine Verbindung zum Cluster herzustellen. -Für jedes Ausführungsmodell gibt es dann einen entsprechenden ``View``. Mit -diesen ``Views`` können Benutzer mit einer Reihe von Engines interagieren. Dabei -sind die beiden Standardansichten: +There is a main object ``Client`` to connect to the cluster. Then there is a +corresponding ``View`` for each execution model. These ``Views`` allow users to +interact with a number of engines. The two standard views are: -- :py:class:`ipyparallel.DirectView`-Klasse für die explizite Adressierung -- :py:class:`ipyparallel.LoadBalancedView`-Klasse für zielunabhängiges Scheduling +- :py:class:`ipyparallel.DirectView` class for explicit addressing +- :py:class:`ipyparallel.LoadBalancedView` class for target-independent scheduling -Starten -------- +Start +----- -#. Starten des IPython-Hub: +#. Starting the IPython Hub: .. code-block:: console @@ -87,29 +86,28 @@ Starten [IPControllerApp] task::using Python leastload Task scheduler … - DB-Backend - Die Datenbank, in der die IPython-Tasks verwaltet werden. Neben der - In-Memory-Datenbank ``DictDB`` sind ``MongoDB`` und ``SQLite`` die weiteren - Optionen. + DB backend + The database in which the IPython tasks are managed. In addition to the + in-memory database ``DictDB``, ``MongoDB`` and ``SQLite`` are further + options. ``ipcontroller-client.json`` - Konfigurationsdatei für den IPython-Client + Configuration file for the IPython client ``ipcontroller-engine.json`` - Konfigurationsdatei für die IPython-Engine + Configuration file for the IPython engine Task-Schedulers - Das mögliche Routing-Schema. ``leastload`` weist Aufgaben immer derjenigen - Engine zu, die die wenigsten offenen Aufgaben hat. Alternativ lasst sich - ``lru`` (Least Recently Used), ``plainrandom``, ``twobin`` und - ``weighted`` auswählen, wobei die beiden letztgenannten zusätzlich Numpy - benötigen. + The possible routing scheme. ``leastload`` always assigns tasks to the + engine with the fewest open tasks. Alternatively, ``lru`` (Least Recently + Used), ``plainrandom``, ``twobin`` and ``weighted`` can be selected, the + latter two also need Numpy. - Dies kann konfiguriert werden in ``ipcontroller_config.py``, z.B. mit - ``c.TaskScheduler.scheme_name = 'leastload'`` oder mit + This can be configured in ``ipcontroller_config.py``, for example with + ``c.TaskScheduler.scheme_name = 'leastload'`` or with .. code-block:: console $ pipenv run ipcontroller --scheme=pure -#. Starten des IPython-Controller und der -Engines: +#. Starting the IPython controller and the engines: .. code-block:: console @@ -119,24 +117,22 @@ Starten [IPClusterStart] Starting Controller with LocalControllerLauncher [IPClusterStart] Starting 4 Engines with LocalEngineSetLauncher - Batch-Systeme - Neben der Möglichkeit, ``ipcontroller`` und ``ipengine`` lokal zu starten, - siehe *Starting the controller and engine on your local machine* in - :ipyparallel:label:`ssh`, dRieas ``LocalControllerLauncher`` - und ``LocalEngineSetLauncher`` starten, gibt es auch noch die Profile - ``MPI``, ``PBS``, `SGE``, ``LSF``, ``HTCondor``, ``Slurm``, - ``SSH`` und ``WindowsHPC``. + Batch systems + Besides the possibility to start ``ipcontroller`` and ``ipengine`` locally, + see *Starting the controller and engine on your local machine* in + :ipyparallel:label:`ssh`, there are also the profiles for ``MPI``, ``PBS``, + `SGE``, ``LSF``, ``HTCondor``, ``Slurm``, ``SSH`` and ``WindowsHPC``. - Dies kann konfiguriert werden in ``ipcluster_config.py`` z.B. mit - ``c.IPClusterEngines.engine_launcher_class = 'SSH'`` oder mit + This can be configured in ``ipcluster_config.py`` for example with + ``c.IPClusterEngines.engine_launcher_class = 'SSH'`` or with - .. code-block:: console + .. code-block:: console $ pipenv run ipcluster start --engines=MPI - .. seealso:: :ipyparallel:doc:`process` + .. seealso:: :ipyparallel:doc:`process` -#. Starten des Jupyter Notebook und Laden der IPython-Parallel-Extension: +#. Starting the Jupyter Notebook and loading the IPython-Parallel-Extension: .. code-block:: console @@ -147,6 +143,6 @@ Starten [I NotebookApp] The Jupyter Notebook is running at: [I NotebookApp] http://localhost:8888/?token=4e9acb8993758c2e7f3bda3b1957614c6f3528ee5e3343b3 -#. Im Browser kann anschließend unter der Adresse - ``http://localhost:8888/tree/docs/parallel/ipyparallel#ipyclusters`` der - Cluster mit dem ``default``-Profil gestartet werden. +#. Finally the cluster with the ``default`` profile can be startet in the + browser at the URL + ``http://localhost:8888/tree/docs/parallel/ipyparallel#ipyclusters``. diff --git a/docs/refactoring/parallel/ipyparallel/magics.ipynb b/docs/refactoring/parallel/ipyparallel/magics.ipynb index e092d991..82ad8d58 100644 --- a/docs/refactoring/parallel/ipyparallel/magics.ipynb +++ b/docs/refactoring/parallel/ipyparallel/magics.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# `ipyparallel`-Magic" + "# `ipyparallel` magics" ] }, { @@ -510,9 +510,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## `%%px` Cell Magic \n", + "## `%%px` cell magic \n", "\n", - "`--targets`, `--block` und `--noblock`" + "`--targets`, `--block` and `--noblock`" ] }, { @@ -1148,9 +1148,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Mehrere aktive Views\n", + "## Multiple active views\n", "\n", - "Magics von `ipyparallel` sind bestimmten `DirectView`-Objekten zugeordnet. Der aktive View kann jedoch geändert werden mit dem Aufruf der `activate()`-Methode auf einem View." + "Magics of `ipyparallel` are assigned to certain `DirectView` objects. However, the active view can be changed by calling the `activate()` method on a view." ] }, { @@ -1199,7 +1199,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr die Anischt aktiviert, könnt ihr auch einen Suffix angeben, so dass dieser bei einer ganzen Reihe von Magics zugeordnet werden kann ohne die bereits vorhandenen zu ersetzen." + "If you activate the view, you can also specify a suffix so that it can be assigned to a whole range of magics without replacing the existing ones." ] }, { @@ -1265,22 +1265,22 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dieses Suffix wird am Ende aller Magics angewendet, also z.B.`%autopx_even`, `%pxresult_even` usw.\n", + "This suffix is used at the end of all magics, e.g.`%autopx_even`, `%pxresult_even` etc.\n", "\n", - "Der Einfachheit halber hat auch `Client` eine `activate()`-Methode, die einen `DirectView` mit `block = True` erstellt, aktiviert und die neue View zurückgibt.\n", + "For the sake of simplicity, also `Client` has an `activate()` method that creates a `DirectView` with `block = True`, activates it, and returns the new view.\n", "\n", - "Die anfänglichen Magics, die beim Erstellen eines Clients registriert werden, sind das Ergebnis des Aufrufs `rc.activate()` mit Standardargumenten." + "The initial magics that are registered when a client is created are the result of the call `rc.activate()` with standard arguments." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Engines als Kernel\n", + "## Engines as kernel\n", "\n", - "Engines sind eigentlich dasselbe Objekt wie IPython-Kernels, mit der einzigen Ausnahme, dass Engines eine Verbindung zu einem Controller herstellen, während reguläre Kernels ihre Sockets direkt an Verbindungen zu ihrem Frontend binden.\n", + "Engines are actually the same object as IPython kernels, with the only exception that engines connect to a controller, while regular kernels bind their sockets directly to connections to their front end.\n", "\n", - "Manchmal werdet ihr zum Debuggen oder Analysieren euer Frontend direkt mit einer Engine verbinden wollen, um eine direktere Interaktion zu ermöglichen. Auch dies könnt ihr tun, indem ihr die Engine anweist, ihren Kernel auch an euer Frontend bindet:" + "Sometimes you will connect your front end directly to an engine for debugging or analysing the interaction more directly. You can also do this by instructing the engine to bind its kernel to your frontend as well:" ] }, { @@ -1297,14 +1297,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Hinweis:** Seid vorsichtig mit dieser Anweisung, da sie so viele QtConsole startet, wie Engines zur Verfügung stehen." + "> **Note:** Be careful with this statement, as it starts as many QtConsoles as there are engines available." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ könnet ihr euch die Verbindungsinformationen auch anzeigen lassen und so ermitteln, wie ihr eine Verbindung zu den Engines herstellen könnt, je nachdem, wo sie leben und wo Sie sich befinden:" + "Alternatively, you can also display the connection information and determine how you can establish a connection to the engines, depending on where they live and where you are:" ] }, { diff --git a/docs/refactoring/parallel/ipyparallel/mpi.ipynb b/docs/refactoring/parallel/ipyparallel/mpi.ipynb index d4b0c3d2..8d2b4e10 100644 --- a/docs/refactoring/parallel/ipyparallel/mpi.ipynb +++ b/docs/refactoring/parallel/ipyparallel/mpi.ipynb @@ -6,32 +6,32 @@ "source": [ "# MPI\n", "\n", - "Oft erfordert ein paralleler Algorithmus das Verschieben von Daten zwischen den *Engines*. Eine Möglichkeit besteht darin, Push und Pull über die `DirectView`. Dies ist jedoch langsam, da alle Daten über den *Controller* zum *Client* und dann wieder zurück zum endgültigen Ziel gelangen müssen.\n", + "Often, a parallel algorithm requires moving data between the engines. One way is to push and pull over the `DirectView`. However, this is slow because all of the data has to get through the controller to the client and then back to the final destination.\n", "\n", - "Eine viel bessere Möglichkeit ist die Verwendung des [Message Passing Interface (MPI)](https://de.wikipedia.org/wiki/Message_Passing_Interface). Die Parallel-Computing-Architektur von IPython wurde von Grund auf für die Integration mit MPI entwickelt. Dieses Notebook gibt eine kurze Einführung in die Verwendung von MPI mit IPython." + "A much better option is to use the [Message Passing Interface (MPI)](https://de.wikipedia.org/wiki/Message_Passing_Interface). IPython's parallel computing architecture was designed from the ground up to integrate with MPI. This notebook gives a brief introduction to using MPI with IPython." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Anforderungen\n", + "## Requirements\n", "\n", - "* Eine Standard-MPI-Implementierung wie [OpenMPI](http://www.open-mpi.org/) oder [MPICH](MPICH). \n", + "* A standard MPI implementation like [OpenMPI](http://www.open-mpi.org/) or [MPICH](MPICH). \n", "\n", - " Für Debian/Ubuntu können diese installiert werden mit\n", + " For Debian/Ubuntu these can be installed with\n", " \n", " ```\n", " $ sudo apt install openmpi-bin\n", " ```\n", " \n", - " oder\n", + " or\n", " \n", " ```\n", " $ sudo apt install mpich\n", " ```\n", "\n", - " Alternativ können OpenMPI oder MPICH auch mit [Spack](../../../productive/envs/spack/use.rst) installiert werden: die Pakete sind `openmpi` oder `mpich`. \n", + " Alternatively, OpenMPI or MPICH can also be installed with [Spack](../../../productive/envs/spack/use.rst): the packages are `openmpi` or `mpich`. \n", "\n", "\n", "* [mpi4py](https://mpi4py.readthedocs.io/)" @@ -41,30 +41,30 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Starten der Engines bei aktiviertem MPI\n", + "## Starting the engines with activated MPI\n", "\n", - "### Automatisches Starten mit `mpiexec` und `ipcluster`\n", + "### Automatic start with `mpiexec` and `ipcluster`\n", "\n", - "Dies kann z.B. erfolgen mit\n", + "This can be done with, e.g.\n", "\n", "```\n", "$ pipenv run ipcluster start -n 4 --profile=mpi\n", "```\n", "\n", - "Hierfür muss jedoch zuvor ein entsprechendes Profil angelegt werden; siehe hierfür [Konfiguration](config.rst).\n", + "For this, however, a corresponding profile must first be created; see [configuration](config.rst).\n", "\n", - "### Automatisches Starten mit PBS und `ipcluster`\n", + "### Automatic start with PBS and `ipcluster`\n", "\n", - "Der `ipcluster`-Befehl bietet auch eine Integration in [PBS](https://www.pbspro.org/). Weitere Informationen hierzu erhaltet ihr in [Using ipcluster in PBS mode](https://ipyparallel.readthedocs.io/en/latest/process.html#using-ipcluster-in-pbs-mode)." + "The `ipcluster` command also offers integration in [PBS](https://www.pbspro.org/). You can find more information about this in [Using ipcluster in PBS mode](https://ipyparallel.readthedocs.io/en/latest/process.html#using-ipcluster-in-pbs-mode)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiel\n", + "## Example\n", "\n", - "Die folgende Notebook-Zelle ruft `psum.py` mit folgendem Inhalt auf:\n", + "The following notebook cell calls `psum.py` with the following content:\n", "\n", "```\n", "from mpi4py import MPI\n", diff --git a/docs/refactoring/parallel/ipyparallel/task.ipynb b/docs/refactoring/parallel/ipyparallel/task.ipynb index 254f516f..a42649db 100644 --- a/docs/refactoring/parallel/ipyparallel/task.ipynb +++ b/docs/refactoring/parallel/ipyparallel/task.ipynb @@ -4,19 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Task-Interface\n", + "# Task interface\n", "\n", - "Die *Task*-Interface zum Cluster präsentiert die *Engines* als fehlertolerantes, dynamisches LoadBalancing für *Workers*. Im Gegensatz zur *Direct*-Interface gibt es bei der *Task*-Interface keinen direkten Zugriff auf einzelne *Engines*. Indem der IPython-Scheduler die *Worker* zuzuweist, wird die Schnittstelle einfacher und zugleich leistungsfähiger.\n", + "The task interface to the cluster presents the engines as a fault-tolerant, dynamic load balancing of Workers. In contrast to the direct interface, the task interface does not have direct access to individual engines. As the IPython scheduler assigns the workers, the interface becomes simpler and more powerful at the same time.\n", "\n", - "Das Beste ist jedoch, dass beide Schnittstellen gleichzeitig verwendet werden können, um die jeweiligen Stärken zu nutzen. Wenn Berechnungen nicht von früheren Ergebnissen abhängen, ist, ist das *Task*-Interface ideal:" + "The best part, however, is that both interfaces can be used at the same time to leverage their respective strengths. If calculations do not depend on previous results, the task interface is ideal:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Erstellen einer `LoadBalancedView`-Instanz\n", - "\n" + "## Create an `LoadBalancedView` instance" ] }, { @@ -68,17 +67,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`load_balanced_view` ist die Standardansicht.\n", + "`load_balanced_view` is the default view.\n", "\n", - "> **Siehe auch**: [Views](https://ipyparallel.readthedocs.io/en/latest/details.html#parallel-details)." + "> **See also:** [Views](https://ipyparallel.readthedocs.io/en/latest/details.html#parallel-details)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Schnelle und einfache Parallelität\n", - "\n" + "## Fast and easy parallelism" ] }, { @@ -115,7 +113,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### `@lview.parallel()`-Decorator" + "### `@lview.parallel()` decorator" ] }, { @@ -146,16 +144,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Abhängigkeiten\n", + "## Dependencies\n", "\n", - "> **Hinweis**: Beachtet bitte, dass der reine ZeroMQ-Scheduler keine Abhängigkeiten unterstützt." + "> **Note:** Please note that the pure ZeroMQ scheduler does not support any dependencies." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Funktionsabhängigkeiten\n", + "### Function dependencies\n", "\n", "`UnmetDependency`" ] @@ -164,21 +162,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### `@ipp.require`-Decorator" + "#### `@ipp.require` decorator" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "#### `@ipp.depend`-Decorator" + "#### `@ipp.depend` decorator" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "#### `dependent`-Objekt\n", + "#### `dependent` object\n", "\n" ] }, @@ -211,7 +209,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Siehe auch:** Manche parallele Workloads können als [Directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) beschrieben werden. In [DAG Dependencies](https://ipyparallel.readthedocs.io/en/latest/dag_dependencies.html#dag-dependencies) wird anhand eines Beispiels beschrieben, wie [NetworkX](../../jupyter/ipywidgets/networkx.html) zur Darstellung der Task-Abhängigkeiten als DAGs dargestellt werden." + "> **See also:** Some parallel workloads can be described as [Directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG). In [DAG Dependencies](https://ipyparallel.readthedocs.io/en/latest/dag_dependencies.html#dag-dependencies) we describe using an example how [NetworkX](../../jupyter/ipywidgets/networkx.html) is used to represent the task dependencies as DAG." ] }, { @@ -225,7 +223,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`retries` und `resubmit`" + "`retries` and `resubmit`" ] }, { @@ -248,13 +246,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "| Schema | Beschreibung |\n", + "| Scheme | Description |\n", "| ------------- | ------------ |\n", - "| `lru` | ***Least Recently Used***: Weist die Worker immer der zuletzt verwendeten *Engine* zu. Ähnlich *Round-Robin* berücksichtigt es jedoch nicht die Laufzeit jeder einzelnen Aufgabe. |\n", - "| `plainrandom` | ***Plain Random***: Wählt zufällig die *Engine* aus, die ausgeführt werden soll. |\n", - "| `twobin` | ***Two-Bin Random***: Benötigt `numpy`. Wählt zwei *Engines* zufällig aus und verwendt die `lru` der beiden. Dies ist häufig besser als die rein zufällige Verteilung, erfordert jedoch einen höheren Rechenaufwand. |\n", - "| `leastload` | ***Least Load***: Standardschema, das die *Engine* immer Aufgaben mit den wenigsten ausstehenden Aufgaben zuweist. |\n", - "| `weighted` | ***Weighted Two-Bin Random***: Gewichtetes ***Two-Bin Random***-Schema. |\n" + "| `lru` | ***Least Recently Used***: Always assigns the workers to the last used engine. Similar to *round robin*, however, it does not take into account the runtime of each individual task. |\n", + "| `plainrandom` | ***Plain Random***: Randomly selects the engine to be run. |\n", + "| `twobin` | ***Two-Bin Random***: Requires `numpy`. Randomly select two engines and use `lru`. This is often better than the purely random distribution, but requires more computational effort. |\n", + "| `leastload` | ***Least Load***: Standard scheme that the engine always assigns tasks with the fewest outstanding tasks. |\n", + "| `weighted` | ***Weighted Two-Bin Random***: Weighted ***Two-Bin Random*** scheme." ] } ], diff --git a/docs/refactoring/parallel/multiprocessing.ipynb b/docs/refactoring/parallel/multiprocessing.ipynb index e27e83d7..589428ed 100644 --- a/docs/refactoring/parallel/multiprocessing.ipynb +++ b/docs/refactoring/parallel/multiprocessing.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Multi-Processing-Beispiel\n", + "# Multi-processing example\n", "\n", - "Wir beginnen hier mit Code, der klar und einfach ist und von oben nach unten ausgeführt wird. Er ist einfach zu entwickeln und inkrementell zu testen:" + "We’ll start with code that is clear, simple, and executed top-down. It’s easy to develop and incrementally testable:" ] }, { @@ -49,14 +49,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Hinweis 1:** Eine gute Entwicklungsstrategie ist die Verwendung von [map](https://docs.python.org/3/library/functions.html#map), um den Code in einem einzelnen Prozess und einem einzelnen Thread zu testen, bevor zu Multi-Processing gewechselt wird.\n", + "> **Note 1:** A good development strategy is to use [map](https://docs.python.org/3/library/functions.html#map), to test your code in a single process and thread before moving to multi-processing.\n", "\n", - "> **Hinweis 2:** Um besser einschätzen zu können, wann `ThreadPool` und wann Prozess-`Pool` verwendet werden sollte, hier einige Faustregeln:\n", + "> **Note 2:** In order to better assess when `ThreadPool` and when process `Pool` should be used, here are some rules of thumb:\n", "> \n", - "> * `multiprocessing.pool.ThreadPool` sollte für IO-lastige Jobs verwendet werden.\n", - "> * `multiprocessing.Pool` sollte für CPU-lastige Jobs verwendet werden.\n", - "> * Für CPU- und IO-lastige Jobs bevorzuge ich üblicherweise `multiprocessing.Pool`, da hierdurch eine bessere Prozessisolierung erreicht wird.\n", - "> * Bei Python 3 schaut euch auch die Pool-Implementierung von [concurrent.future.Executor](https://docs.python.org/3/library/concurrent.futures.html?highlight=concurrent%20futures#concurrent.futures.Executor) an." + "> * `multiprocessing.pool.ThreadPool` should be used for IO-heavy jobs.\n", + "> * `multiprocessing.Pool` should be used for CPU-heavy jobs.\n", + "> * For jobs that are heavy on the CPU and IO, I usually prefer `multiprocessing.Pool`, as this achieves better process isolation.\n", + "> * For Python 3, take a look at the pool implementation of [concurrent.future.Executor](https://docs.python.org/3/library/concurrent.futures.html?highlight=concurrent%20futures#concurrent.futures.Executor)." ] }, { @@ -98,21 +98,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Was ist parallelisierbar?\n", + "## What can be parallelised?\n", "\n", - "### Amdahlsche Gesetz\n", + "### Amdahl’s law\n", "\n", - "> Der Geschwindigkeitszuwachs vor allem durch den sequentiellen Anteil des Problems beschränkt, da sich dessen Ausführungszeit durch Parallelisierung nicht verringern lässt. Zudem entstehen durch Parallelisierung zusätzliche Kosten wie etwa für die Kommunikation und die Synchronisierung der Prozesse.\n", + "> The increase in speed is mainly limited by the sequential part of the problem, since its execution time cannot be reduced by parallelisation. In addition, parallelisation creates additional costs, such as for communication and synchronisation of the processes.\n", "\n", - "In unserem Beispiel können die folgenden Aufgaben nur seriell abgearbeitet werden:\n", + "In our example, the following tasks can only be processed serially:\n", "\n", - "* UDP DNS request für die URL\n", + "* UDP DNS request request for the URL\n", "* UDP DNS response\n", - "* Socket vom OS\n", + "* Socket from the OS\n", "* TCP-Connection\n", - "* Senden des HTTP Request für die Root-Ressource\n", - "* Warten auf die TCP Response\n", - "* Zählen der Zeichen auf der Website" + "* Sending the HTTP request for the root resource\n", + "* Waiting for the TCP response\n", + "* Counting characters on the site" ] }, { @@ -155,18 +155,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Hinweis:** [imap_unordered](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.Pool.imap_unordered) wird verwendet, um die Reaktionsfähigkeit zu verbessern. Dies ist jedoch nur möglich, da die Funktion das Argument und das Ergebnis als Tuple zurückgibt." + "> **Note:** [imap_unordered](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.Pool.imap_unordered) is used to improve responsiveness. However, this is only possible because the function returns the argument and result as a tuple." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Tipps\n", + "## Tips\n", "\n", - "* Macht nicht zu viele Trips hin und her\n", + "* Don’t make too many trips back and forth\n", "\n", - " Erhaltet ihr zu viele iterierbare Ergebnisse, ist dies ein guter Indikator für zu viele Trips, wie z.B. in\n", + " If you get too many iterable results, this is a good indicator of too many trips, such as in\n", "\n", " def sitesize(url, start):\n", " req = urllib.request.Request()\n", @@ -175,9 +175,9 @@ " block = u.read()\n", " return url, len(block)\n", "\n", - "* Macht auf jedem Trip relevante Fortschritte\n", + "* Make relevant progress on every trip\n", "\n", - " Sobald ihr den Prozess erhaltet, solltet ihr deutliche Fortschritte erzielen und euch nicht verzetteln. Das folgende Beispiel verdeutlicht zu kleine Zwischenschritte:\n", + " Once you get the process, you should make significant progress and not get bogged down. The following example illustrates intermediate steps that are too small:\n", "\n", " def sitesize(url, results):\n", " with urllib.request.urlopen(url) as u:\n", @@ -185,9 +185,9 @@ " line = u.readline()\n", " results.put((url, len(line)))\n", "\n", - "* Sendet und empfangt nicht zu viele Daten\n", + "* Don’t send or receive too much data\n", "\n", - " Das folgende Beispiel erhöht unnötig die Datenmenge:\n", + " The following example unnecessarily increases the amount of data:\n", "\n", " def sitesize(url):\n", " u = urllib.request.urlopen(url)\n", diff --git a/docs/refactoring/parallel/threading-example.ipynb b/docs/refactoring/parallel/threading-example.ipynb index c837b178..9720571b 100644 --- a/docs/refactoring/parallel/threading-example.ipynb +++ b/docs/refactoring/parallel/threading-example.ipynb @@ -4,14 +4,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Threading-Beispiel" + "# Threading example" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Aktualisieren und Ausgeben eines Counters:" + "## Updating and displaying a counter:" ] }, { @@ -52,18 +52,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Beginnt mit Code, der klar und einfach ist und von oben nach unten ausgeführt wird. Er ist einfach zu entwickeln und inkrementell zu testen.\n", - "\n", - "> **Hinweis:** Testet und debuggt eure Anwendung bevor ihr mit Threading beginnt. Threading macht das Debugggen niemals einfacher." + "Start with code that is clear, simple, and top-down. It’s easy to develop and incrementally testable.\n", + " \n", + "> **Note:** Test and debug your application before starting threading. Threading never makes debugging easier." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Umwandeln in Funktionen\n", + "## Convert to functions\n", "\n", - "Im nächsten Schritt wird dann wiederverwendbarer Code als Funktion erstellt:" + "The next step is to create reusable code as a function:" ] }, { @@ -112,7 +112,7 @@ "source": [ "## Multi-Threading\n", "\n", - "Jetzt können einige Worker-Threads gestartet werden:" + "Now some worker threads can be started:" ] }, { @@ -163,15 +163,15 @@ "source": [ "## Test\n", "\n", - "Ein einfacher Testlauf gleicht perfekt der ursprünglichen Ausgabe.\n", + "A simple test run leads to the same result.\n", "\n", - "### Erkennen von Race Conditions\n", + "### Detection of race conditions\n", "\n", - "> **Hinweis:** Tests können nicht die Abwesenheit von Fehlern beweisen. Viele interessante Race Conditions zeigen sich nicht in Testumgebungen.\n", + "> **Note:** Tests cannot prove the absence of errors. Many interesting race conditions do not show up in test environments.\n", "\n", "### Fuzzing\n", "\n", - "Fuzzing ist eine Technik um das Erkennen von Race Conditions zu verbessern:" + "Fuzzing is a technique to improve the detection of race conditions:" ] }, { @@ -224,32 +224,32 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Diese Technik ist auf relativ kleine Blöcke von Code beschränkt und ist insofern unvollkommen, als sie weiterhin nicht die Abwesenheit von Fehlern beweisen kann. Dennoch können Fuzzed Tests ggf. Race Conditions aufdecken." + "This technique is limited to relatively small blocks of code and is imperfect in that it still cannot prove the absence of errors. Nevertheless, fuzzed tests can reveal race conditions." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Sorgfältiges Threading mit Queues\n", + "## Careful threading with queues\n", "\n", - "Dabei sind folgende Regeln zu beachten:\n", + "The following rules must be observed:\n", "\n", - "1. Alle gemeinsamen Ressourcen sollten in genau einem Thread ausgeführt werden. Alle Kommunikation mit diesem Thread sollte mit nur einer atomaren Message Queue erfolgen – in der Regel mit dem [Queue-Modul](https://docs.python.org/3/library/queue.html), E-Mail oder Message Queues wie [RabbitMQ](https://www.rabbitmq.com/) oder [ZeroMQ](http://zeromq.org/).\n", + "1. All shared resources should be executed in exactly one thread. All communication with this thread should be done with only one atomic message queue – usually with the [queue module](https://docs.python.org/3/library/queue.html), email or message queues such as [RabbitMQ](https://www.rabbitmq.com/) or [ZeroMQ](http://zeromq.org/).\n", "\n", - " Ressourcen, die diese Technik benötigen sind z.B. globale Variablen, Benutzereingaben, Ausgabegeräte, Dateien, Sockets usw.\n", + " Resources that require this technology include global variables, user inputs, output devices, files, sockets, etc.\n", "\n", - "2. Eine Kategorie von Sequenzierungsproblemen besteht im Ssicherzustellen, dass Schritt A vor Schritt B ausgeführt wird. Die Lösung besteht darin, beide im selben Thread auszuführen, in dem alle Aktionen nacheinander ablaufen.\n", + "2. One category of sequencing problems is to ensure that step A is performed before step B. The solution is to run them both on the same thread, with all the actions happening in sequence.\n", "\n", - "3. Um eine *Barriere* zu implementieren, die darauf wartet, dass alle parallelen Threads abgeschlossen sind, müssen nur alle Threads mit join() verbunden werden.\n", + "3. To implement a *barrier* that waits for all parallel threads to complete, just join all threads with join().\n", "\n", - "4. Ihr könnt nicht darauf warten, dass Daemon-Threads abgeschlossen werden (sie sind Endlosschleifen); stattdessen solltet ihr join() auf der Queue selbst ausführen, so dass die Aufgaben erst zusammengefügt werden wenn alle Aufgaben in der Queue erledigt sind.\n", + "4. You cannot wait for daemon threads to complete (they are infinite loops); instead you should execute join() on the queue itself, so that the tasks are only merged when all tasks in the queue have been completed.\n", "\n", - "5. Ihr könnt globale Variablen verwenden um zwischen Funktionen zu kommunizieren, allerdings nur innerhalb eines single-threaded Programm. In einem multi-thread-Programm könnt ihr globale Variablen jedoch nicht verwenden da sie mutable sind. Dann ist die bessere Lösung threading.local(), da sie in einem Thread zwar global ist, jedoch nicht darüber hinaus.\n", + "5. You can use global variables to communicate between functions, but only within a single-threaded program. In a multi-thread program, however, you cannot use global variables because they are mutable. Then the better solution is threading.local(), since it is global in a thread, but not beyond.\n", "\n", - "6. Versucht niemals, einen Thread von außen zu beenden: ihr wisst nie, ob dieser Thread ein Lock einthält. Daher bietet Python auch keinen direkten Mechanismus zum beenden von Threads. Falls ihr dies jedoch mit ctypes versucht, ist dies ein Rezept für einen Deadlocks.\n", + "6. Never try to terminate a thread from the outside: you never know if that thread is holding a lock. Therefore, Python does not provide a direct thread termination mechanism. However, if you try to do this with ctypes, this is a recipe for deadlock.\n", "\n", - "Wenn wir nun diese Regeln anwenden, sieht unser Code so aus:" + "Now, if we apply these rules, our code looks like this:" ] }, { @@ -336,9 +336,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Sorgfältiges Threading mit Locks\n", + "## Careful threading with locks\n", "\n", - "Wenn wir Threading mit Locks statt mit Queues machen, wirkt der Code noch aufgeräumter:" + "If we thread with locks instead of queues, the code looks even tidier:" ] }, { @@ -399,11 +399,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Schließlich noch einige Hinweise zu Locks:\n", + "Finally, a few notes on locks:\n", "\n", - "1. Locks sind nur sog. *Flags*, sie verhindern nicht wirklich zuverlässig.\n", - "2. Im Allgemeinen sollten Locks als primitives Hilfsmittel betrachtet werden, das in nicht-trivialen Beispielen schwierig zu verstehen ist. Bei komplexeren Anwendungen sollten also besser atomare Message Queues verwendet werden.\n", - "3. Je mehr Locks gleichzeitig gesetzt sind, desto geringer werden die Vorteile gleichzeitiger Verarbeitung." + "1. Locks are just so-called *flags*, they are not really reliable.\n", + "2. In general, locks should be viewed as a primitive tool that is difficult to understand in non-trivial examples. For more complex applications, it is better to use atomic message queues.\n", + "3. The more locks that are set at the same time, the less the benefits of simultaneous processing." ] } ], diff --git a/docs/refactoring/parallel/threading-forking-combined.ipynb b/docs/refactoring/parallel/threading-forking-combined.ipynb index 5d8fbe17..83565f03 100644 --- a/docs/refactoring/parallel/threading-forking-combined.ipynb +++ b/docs/refactoring/parallel/threading-forking-combined.ipynb @@ -4,11 +4,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Threading und Forking kombinieren\n", + "# Threading and forking combined\n", "\n", - "Das Mischen von Multiprocessing und Threading ist generell problematisch und ein Rezept für Deadlocks.\n", + "Mixing multiprocessing and threading is generally problematic and a recipe for deadlocks.\n", "\n", - "Der folgende Code wurde 2016 unter https://bugs.python.org/issue27422 im Python Bugtracker eingetragen:" + "The following code was entered in 2016 at https://bugs.python.org/issue27422 in the Python bug tracker:" ] }, { @@ -105,7 +105,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Üblicherweise empfiehlt sich Threading nach dem Fork, nicht vorher. Andernfalls werden die beim Ausführen der Threads verwendeten Locks über die Prozesse dupliziert. Stirbt einer dieser Prozesse mit einem Lock, so geraten alle anderen Prozesse mit diesem Lock in einen Deadlock." + "Usually, threading is recommended after the fork, not before. Otherwise, the locks used when executing the threads are duplicated across the processes. If one of these processes dies with a lock, all other processes with this lock are deadlocked." ] } ], diff --git a/docs/viz/index.rst b/docs/viz/index.rst index 7cab9efe..868a66ce 100644 --- a/docs/viz/index.rst +++ b/docs/viz/index.rst @@ -1,5 +1,5 @@ -Daten visualisieren -=================== +Visualise data +============== -Wir haben die Visualisierung von Daten in ein eigenes Tutorial ausgelagert: +We have outsourced the visualisation of data to a separate tutorial: :doc:`PyViz Tutorial `. diff --git a/docs/web/dashboards/appmode/index.rst b/docs/web/dashboards/appmode/index.rst index 928962b7..ba434c46 100644 --- a/docs/web/dashboards/appmode/index.rst +++ b/docs/web/dashboards/appmode/index.rst @@ -1,7 +1,7 @@ Appmode ======= -Jupyter-Erweiterung, die aus Notebooks Webanwendungen macht. +Jupyter extension that turns notebooks into web applications. .. toctree:: :titlesonly: @@ -10,21 +10,20 @@ Jupyter-Erweiterung, die aus Notebooks Webanwendungen macht. app-example.ipynb -Beispiel --------- +Example +------- -Beim Klick auf :menuselection:`Appmode` wird aus dem Notebook -`app-example.ipynb `_ ein übersichtliche Web-Anwendung für -einen Rechner: +When you click on :menuselection:`Appmode` the notebook `app-example.ipynb +`_ becomes a clear web application for a calculator: .. image:: appmode-app.png :scale: 53% - :alt: Appmode-App + :alt: Appmode app Installation ------------ -Für den Jupyter-Service muss ``appmode`` installiert werden mit +For the Jupyter service ``appmode`` must be installed with .. code-block:: console @@ -50,35 +49,35 @@ Für den Jupyter-Service muss ``appmode`` installiert werden mit - Validating... appmode.server_extension OK -Konfiguration +Configuration ------------- -Serverseitige Konfiguration -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Server-side configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ -Der Server kann mit folgenden drei Optionen konfiguriert werden: +The server can be configured with the following three options: ``Appmode.trusted_path`` - führt den App-Modus nur für Notizbücher unter diesem Pfad aus; - Voreinstellung: *Keine Einschränkungen*. + runs the app mode only for notebooks under this path; Default setting: *no + restrictions*. ``Appmode.show_edit_button`` - zeigt :menuselection:`Edit App`-Taste im App-Modus an; Voreinstellung: - ``True`` + displays :menuselection:`Edit App` button in app mode; Default setting: + ``True``. ``Appmode.show_other_buttons`` - zeigt andere Schaltflächen im App-Modus an, z.B. :menuselection:`Logout`; - Voreinstellung: ``True`` + shows other buttons in app mode, e.g. :menuselection:`Logout`; Default + setting: ``True``. -Weitere Infos zur Server-Konfiguration erhaltet ihr in +You can find more information about the server configuration in :doc:`/workspace/jupyter/notebook/config`. -Clientseitige Konfiguration -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Client-side configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ -Die UI-Elemente können auch clientseitig in der `custom.js -`_-Datei -angepasst werden, z.B. mit: +The UI elements can also be adapted on the client side in the `custom.js +`_ +file, e.g. with: .. code-block:: Javascript @@ -92,5 +91,5 @@ angepasst werden, z.B. mit: $('#appmode-loader').append('

Loading...

'); .. note:: - Das Ausblenden der :menuselection:`Edit App`-Taste hindert Benutzer nicht am - Verlassen des App-Modus, indem die URL manuell geändert wird. + Hiding the :menuselection:`Edit App` button does not prevent users from + exiting app mode by manually changing the URL. diff --git a/docs/web/dashboards/index.rst b/docs/web/dashboards/index.rst index e7a8a6aa..280cb265 100644 --- a/docs/web/dashboards/index.rst +++ b/docs/web/dashboards/index.rst @@ -2,34 +2,33 @@ Dashboards ========== :doc:`Jupyter Dashboards Layout Extension ` - Add-On für Jupyter-Notebooks, womit Outputs (Text, Plots, Widgets usw.) in - einem Gestaltungsraster oder in Berichtform angeordnet werden können. + Add-on for Jupyter notebooks, with which outputs (text, plots, widgets, + etc.) can be arranged in a design grid or in report form. :doc:`appmode/index` - Jupyter-Erweiterung, die aus Notebooks Webanwendungen macht. + Jupyter extension that turns notebooks into web applications. :doc:`/workspace/jupyter/nbviewer` - Er eignet sich hervorragend zum Anzeigen statischer Berichte, kann - aber auch zusammen mit :doc:`interaktiven Widgets - ` verwendet werden, deren Status im - Notebook-Dokument selbst gespeichert werden. + It's great for viewing static reports, but it can also be used in + conjunction with :doc:`interaktiven Widgets + `. :doc:`panel/index` - wurde auf Basis von `Bokeh `_ und - `Param `_ entwickelt und bietet ein Toolkit - speziell zur Erstellung von Apps und Dashboards, das jedoch nicht nur - Bokeh-Plots unterstützt, s.a. `Panel: Ahigh-level app and dashboarding - solution for the PyData ecosystem + was developed on the basis of `Bokeh `_ + and `Param `_ and offers a toolkit + especially for creating apps and dashboards, which not only supports bokeh + plots, see also `Panel: Ahigh-level app and dashboarding solution for the + PyData ecosystem `_. :doc:`voila/index` - wurde von `QuantStack `_ entwickelt, s.a. `And + was developed by `QuantStack `_, see also `And voilà! `_. -Aktivitäten und Lizenzen ------------------------- +Activities and licenses +----------------------- -Mit diesem tabellarischen Überblick könnt ihr schnell die Aktivitäten und -Lizenzen der verschiedenen Bibliotheken vergleichen. +With this tabular overview you can quickly compare the activities and licenses +of the various libraries. .. csv-table:: GitHub-Insights: Dashboards - :header: "Name", "Stars", "Mitwirkende", "Commit-Aktivität", "Lizenz" + :header: "Name", "Stars", "Contributors", "Commit activity", "License" "`Jupyter Dashboards Layout Extension `_",".. image:: https://raster.shields.io/github/stars/jupyter-attic/dashboards",".. image:: https://raster.shields.io/github/contributors/jupyter-attic/dashboards",".. image:: https://raster.shields.io/github/commit-activity/y/jupyter-attic/dashboards",".. image:: https://raster.shields.io/github/license/jupyter-attic/dashboards" "`Appmode `_",".. image:: https://raster.shields.io/github/stars/oschuett/appmode",".. image:: https://raster.shields.io/github/contributors/oschuett/appmode",".. image:: https://raster.shields.io/github/commit-activity/y/oschuett/appmode",".. image:: https://raster.shields.io/github/license/oschuett/appmode" diff --git a/docs/web/dashboards/jupyter-dashboards/index.rst b/docs/web/dashboards/jupyter-dashboards/index.rst index 5ec19763..a5b6df86 100644 --- a/docs/web/dashboards/jupyter-dashboards/index.rst +++ b/docs/web/dashboards/jupyter-dashboards/index.rst @@ -1,40 +1,39 @@ Jupyter Dashboards ================== -Die `Jupyter Dashboards Layout Extension -`_ ist ein Add-On für -Jupyter-Notebooks, womit Outputs (Text, Plots, Widgets usw.) in einem -Gestaltungsraster oder in Berichtform angeordnet werden können. Sie speichert -die Informationen zum Layout direkt im Notebook, sodass andere Nutzer dieser -Erweiterung das Notebook ebenfalls im entsprechenden Notebook angezeigt -bekommen. Beispiele für Dashboards findet ihr in `Jupyter Dashboards Demos +The `Jupyter Dashboards Layout Extension +`_ is an add-on for Jupyter +notebooks, with which outputs (text, plots, widgets, etc.) can be arranged in a +design grid or in report form. It saves the information on the layout directly +in the notebook so that other users of this extension can also see the notebook +in the same layout. For examples of dashboards, see `Jupyter Dashboards Demos `_. -Use Case +Use case -------- -Die Jupyter Dashboards sollten folgendes Problem lösen: +The Jupyter dashboards should solve the following problem: -#. Alice erstellt ein Jupyter Notebook mit Plots und interaktiven Widgets. -#. Alice ordnet die Notebook-Zellen in einem Raster- oder Report-Format an. -#. Alice stellt das Dashboard auf einem Dashboard-Server bereit. -#. Bob ruft das Dashboard auf dem `Jupyter Dashboards Server - `_ auf und interagiert - mit Alice Dashboard-Applikation. -#. Alice aktualisiert ihr Jupyter Notebook und stellt das Dashboard anschließend - erneut auf dem Dashboard-Server bereit. +#. Alice creates a Jupyter notebook with plots and interactive widgets. +#. Alice arranges the notebook cells in a grid or report format. +#. Alice provides the dashboard on a dashboard server. +#. Bob calls up the dashboard on the `Jupyter Dashboards Server + `_ and interacts with + Alice Dashboard application. +#. Alice updates her Jupyter notebook and then makes the dashboard available + again on the dashboard server. .. note:: - Für die Schritte 3–5 werden zusätzlich `Jupyter Dashboards Bundler - `_ und `Jupyter + For steps 3–5, `Jupyter Dashboards Bundler + `_ and `Jupyter Dashboards Server `_ - benötigt; beide sind jedoch mittlerweile in Status *retired*, sollten also - nicht weiter verwendet werden. + are also required; however, both are now retired and should not be used any + longer. - Die Roadmap für das :ref:`Voila-Gridstack-Template ` sieht - vor, die gesamte Spezifikation für die Jupyter-Dashboards zu unterstützen. - Aktuell ist das Voilà-Gridstack-Template jedoch noch in einem frühen - Entwicklungsstadium s.a. `And voilà! + The roadmap for the :ref:`Voila-Gridstack-Template ` is to + support the entire specification for the Jupyter dashboards. Currently, + however, the Voilà gridstack template is still in an early stage of + development, see also `And voilà! `_. .. toctree:: diff --git a/docs/web/dashboards/jupyter-dashboards/install.rst b/docs/web/dashboards/jupyter-dashboards/install.rst index 47ac2a67..507285c1 100644 --- a/docs/web/dashboards/jupyter-dashboards/install.rst +++ b/docs/web/dashboards/jupyter-dashboards/install.rst @@ -1,5 +1,5 @@ -Installation der Jupyter Dashboards -=================================== +Installation of Jupyter dashboards +================================== .. code-block:: console diff --git a/docs/web/dashboards/jupyter-dashboards/matplotlib-example.ipynb b/docs/web/dashboards/jupyter-dashboards/matplotlib-example.ipynb index c3be735b..37351888 100644 --- a/docs/web/dashboards/jupyter-dashboards/matplotlib-example.ipynb +++ b/docs/web/dashboards/jupyter-dashboards/matplotlib-example.ipynb @@ -16,13 +16,13 @@ } }, "source": [ - "# Matplotlib-Beispiel\n", + "# Matplotlib example\n", "\n", - "Dieses Notebook demonstriert die Verwendung von `matplotlib` in einem Jupyter-Dashboard.\n", + "This notebook demonstrates the use of `matplotlib` in a Jupyter dashboard.\n", "\n", - "1. Zum Ausführen klickt im Notebook-Menü auf *Cell* → *Run All*.\n", - "2. Anschließend könnt ihr euch mit *View* → *Dashboard-Preview* , das Diagramm im *Report Layout* anschauen.\n", - "3. In *View* → *Dashboard Layout* → *Grid Layout* könnt ihr euch den Plott auch im Rasterlayout anzeigen lassen." + "1. To run it, click on *Cell* → *Run All* in the Notebook menu.\n", + "2. Then you can use *View* → *Dashboard-Preview* to view the diagram in the *Report Layout*.\n", + "3. In *View* → *Dashboard Layout* → *Grid Layout* you can also display the plot in the *Grid Layout*." ] }, { diff --git a/docs/web/dashboards/jupyter-dashboards/use.rst b/docs/web/dashboards/jupyter-dashboards/use.rst index c1e868ab..c64bbc6c 100644 --- a/docs/web/dashboards/jupyter-dashboards/use.rst +++ b/docs/web/dashboards/jupyter-dashboards/use.rst @@ -1,37 +1,36 @@ -Dashboard-Layouts erstellen -=========================== +Create dashboard layouts +======================== -Ihr könnt ein normales Notebook verwenden mit Markdown- und Code-Zellen. Wenn -ihr die Zellen ausführt, werden Text, Diagramme, Widgets usw. generiert. -Anschließend könnt ihr in :menuselection:`Dashboard View` -:menuselection:`Grid Layout` oder :menuselection:`Report Layout` auswählen: +You can use a normal notebook with markdown and code cells. When you run the +cells, text, charts, widgets, etc. are generated. Then you can choose in the +:menuselection:`Dashboard View` either :menuselection:`Grid Layout` or +:menuselection:`Report Layout`: .. image:: dashboard-view.png :scale: 53% - :alt: Optionen für die Dashboard-Ansicht + :alt: Dashboard view options -Beim :menuselection:`Grid Layout` könnt ihr die Größe der Zellen im Raster -ändern und sie verschieben. Ihr könnt auch -:menuselection:`Cell --> Dashboard` verwenden: +With the :menuselection:`Grid Layout` you can change the size of the cells in +the grid and move them. You can also use :menuselection:`Cell --> Dashboard`: .. image:: dashboard-cell-menu.png :scale: 53% - :alt: Cell-Menü mit Dashboard-Optionen + :alt: Cell menu with dashboard options -Im :menuselection:`Report Layout` könnt ihr Zellen anzeigen oder ausblenden. +In the :menuselection:`Report Layout` you can show or hide cells. -In beiden Layouts könnt ihr auf :menuselection:`MORE INFO` klicken um -zusätzliche Informationen angezeigt zu bekommen: +In both layouts you can click on :menuselection:`MORE INFO` to get additional +information: .. image:: dashboard-info.png :scale: 53% - :alt: Dashboard-Info + :alt: Dashboard info -Mit :menuselection:`Dashboard Preview` bekommt ihr eine Vorschau angezeigt, z.B. -für :doc:`matplotlib-example`: +With :menuselection:`Dashboard Preview` you get a preview, e.g. for the +:doc:`matplotlib-example`: .. image:: dashboard-matplotlib-example.png :scale: 53% - :alt: Dashboard mit Matplotlib-Beispiel + :alt: Dashboard with matplotlib example -:menuselection:`View --> Notebook` bringt euch zurück zum Notebook-Editor. +:menuselection:`View --> Notebook` brings you back to the notebook editor. diff --git a/docs/web/dashboards/panel/deploy.ipynb b/docs/web/dashboards/panel/deploy.ipynb index 91216b68..7ee52b17 100644 --- a/docs/web/dashboards/panel/deploy.ipynb +++ b/docs/web/dashboards/panel/deploy.ipynb @@ -4,18 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Deploy und Export\n", + "# Deploy and export\n", "\n", - "Eines der Hauptentwurfsziele für Panel bestand darin, einen nahtlosen Übergang zwischen interaktivem Prototyping eines Dashboards und der Bereitstellung als eigenständige Server-App zu ermöglichen. In diesem Notebook wird gezeigt, wie Panels interaktiv angezeigt, statische Ausgaben eingebettet, ein Snapshot gespeichert und als separate Webserver-App bereitgestellt werden." + "One of the main design goals for Panel was to enable a seamless transition between interactively prototyping a dashboard and deploying it as a standalone server app. This notebook shows how to interactively display panels, embed static output, save a snapshot, and serve it as a separate web server app." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Ausgabe konfigurieren\n", + "## Configure output\n", "\n", - "Panel-Objekte werden automatisch in einem Notebook angezeigt und nutzen [Jupyter Comms](https://jupyter-notebook.readthedocs.io/en/stable/comms.html), um die Kommunikation zwischen der gerenderten App und dem Jupyter-Kernel zu unterstützen. Das Anzeigen eines Panel-Objekts im Notebook ist einfach: es muss nur zunächst die `panel.extension` geladen werden, um das erforderliche JavaScript im Notebook-Kontext zu initialisieren." + "Panel objects are automatically displayed in a notebook and use [Jupyter Comms](https://jupyter-notebook.readthedocs.io/en/stable/comms.html) to support communication between the rendered app and the Jupyter kernel. The display of a panel object in the notebook is simple: it only has to load the `panel.extension` first in order to initialise the required JavaScript in the notebook context." ] }, { @@ -1371,9 +1371,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Optionale Abhängigkeiten \n", + "## Optional dependencies \n", "\n", - "Um bestimmte Komponenten wie Vega, LaTeX und Plotly-Plots verwenden zu können, müssen die entsprechenden Javascript-Komponenten ebenfalls geladen werden. Hierfür könnt ihr sie einfach als Teil des Aufrufs von `pn.extension` angeben:" + "In order to be able to use certain components such as Vega, LaTeX and Plotly-Plots, the corresponding Javascript components must also be loaded. To do this, you can simply include them as part of the call to `pn.extension`:" ] }, { @@ -2916,9 +2916,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## JS und CSS initialisieren \n", + "## Initialise JS and CSS \n", "\n", - "Auch zusätzliches CSS- und Javascript kann mit `css_files`, `js_files` und `raw_css` angegeben werden. Dabei sollte `js_files` als Dictionary-Mapping vom exportierten JS-Modulnamen zur URL mit den JS-Komponenten angegeben werden während `css_files` als Liste definiert werden kann:" + "Additional CSS and Javascript can also be specified with `css_files`, `js_files` and `raw_css`. `js_files` should be specified as a dictionary mapping from the exported JS module name to the URL with the JS components, while `css_files` can be defined as a list:" ] }, { @@ -4459,9 +4459,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Mit diesem `raw_css`-Argument könnt ihr eine Liste von Zeichenfolgen mit CSS definieren, die als Teil des Notebooks und der App veröffentlicht werden sollen.\n", + "With this `raw_css` argument you can define a list of strings with CSS that should be published as part of the notebook and the app.\n", "\n", - "Das Bereitstellen von Keyword-Argumenten mit `extension` entspricht dem Festlegen mit `pn.config`. `pn.config` ist der bevorzugte Ansatz um außerhalb eine Notebooks Javascript- und CSS-Dateien hinzuzufügen:" + "Providing keyword arguments with `extension` is equivalent to specifying with `pn.config`. `pn.config` is the preferred approach to add Javascript and CSS files outside of a notebook:" ] }, { @@ -4478,9 +4478,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Anzeige im Notebook\n", + "## Display in the notebook\n", "\n", - "Sobald `extension` geladen ist, werden Panel-Objekte, die am Ende einer Zelle platziert werden, angezeigt:" + "Once `extension` is loaded, panel objects that are placed at the end of a cell are displayed:" ] }, { @@ -4597,9 +4597,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Die `display`-Funktion \n", + "## The `display` function\n", "\n", - "Um zu vermeiden, dass ein Panel in die letzte Zeile einer Notebook-Zelle gestellt werden muss, könnt ihr die IPython-`display`-Funktion verwenden:" + "To avoid having to put a panel in the last row of a notebook cell, you can use the IPython `display` function:" ] }, { @@ -4716,9 +4716,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Inline-Apps\n", + "## Inline apps\n", "\n", - "Schließlich ist es auch möglich, ein Panel-Objekt als Bokeh-Server-App im Notebook anzuzeigen. Ruft dazu die `.app`-Methode im Panel-Objekt auf und gebt die URL eures Notebook-Servers an:" + "Finally, it is also possible to display a panel object as a bokeh server app in the notebook. To do this, call the `.app` method in the panel object and enter the URL of your notebook server:" ] }, { @@ -4760,54 +4760,54 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die App wird jetzt in einer Instanz des Bokeh-Servers ausgeführt, die vom Jupyter-Notebook-Kernel getrennt ist, sodass ihr schnell testen könnt, ob die gesamte Funktionalität eurer App sowohl im Notebook als auch im Serverkontext funktioniert." + "The app is now executed in an instance of the Bokeh server that is separate from the Jupyter notebook kernel, so that you can quickly test whether the entire functionality of your app works both in the notebook and in the server context." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Anzeige in einem interaktiven Python-Fenster (REPL)\n", + "## Display in an interactive Python window (REPL)\n", "\n", - "Wenn ihr über die Befehlszeile arbeitet, werden nicht automatisch umfangreiche Darstellungen inline dargestellt, wie dies in einem Notebook der Fall ist. Ihr könnt jedoch mit euren Panel-Komponenten interagieren, wenn ihr eine Bokeh-Serverinstanz startet und mit der `show`-Methode ein separates Browserfenster öffnet. Die Methode hat folgende Argumente:\n", + "If you work via the command line, extensive displays are not automatically displayed inline, as is the case in a notebook. However, you can interact with your panel components if you start a Bokeh server instance and use the `show` method to open a separate browser window. The method has the following arguments:\n", "\n", - "* `port`: `int`, (optional): erlaubt die Angabe eines spezifischen Ports (`default=0` wählt einen beliebigen offenen Port)\n", - "* `websocket_origin`: `str` oder `list(str)` (optional): Eine Liste von Hosts, die sich mit dem Websocket verbinden können. Dies ist erforderlich wenn eine Server-App in eine externe Website eingebettet wird. Wenn keine Angabe gemacht wird, wird `localhost` verwendet.\n", - "* `threaded`: `boolean` (optional, `default=False`): `True` startet den Server in einem separaten Thread und erlaubt euch, interaktiv mit der App agieren zu können.\n", + "* `port`: `int`, (optional): allows a specific port to be specified (`default=0` select any open port)\n", + "* `websocket_origin`: `str` or `list(str)` (optional): A list of hosts that can connect to the websocket. This is necessary when a server app is embedded in an external website. If not specified, `localhost` is used.\n", + "* `threaded`: `boolean` (optional, `default=False`): `True` starts the server in a separate thread and allows you to interact with the app.\n", "\n", - "Der `show`-Aufruf gibt entweder eine Bokeh-Serverinstanz (`threaded=False`) oder eine `StoppableThread`-Instanz (`threaded=True`) zurück, die beide eine `stop`-Methode zum Stoppen der Serverinstanz bereitstellen." + "The `show` call returns either a Bokeh server instance (`threaded=False`) or an `StoppableThread` instance (`threaded=True`), both provide a `stop` method for stopping the server instance." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Starten eines Servers in der Befehlszeile \n", + "## Starting a server from the command line \n", "\n", - "Panel (und Bokeh) stellen einen CLI-Befehl zum Bereitstellen eines Python-Skripts, eines App-Verzeichnisses oder eines Jupyter-Notebooks mit einer Bokeh- oder Panel-App bereit. Um einen Server über die CLI zu starten, führt einfach Folgendes aus:\n", + "Panel (and Bokeh) provide a CLI command to deploy a Python script, app directory, or Jupyter notebook with a Bokeh or Panel app. To start a server using the CLI, simply do the following:\n", "\n", " $ pipenv run panel serve app.ipynb\n", "\n", - "Um ein Notebook in eine bereitstellbare App zu verwandeln, hängt einfach an ein oder mehrere Panel-Objekte `.servable()` an, wodurch die App zu Bokehs `curdoc` hinzufügt. Auf diese Weise ist es einfach, Dashboards interaktiv in einem Notebook zu erstellen und sie dann nahtlos auf dem Bokeh-Server bereitzustellen." + "To turn a notebook into a deployable app, simply attach to one or more panel objects `.servable()`, which adds the app to bokehs `curdoc`. This makes it easy to create dashboards interactively in a notebook and then seamlessly provide them to the Bokeh server." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Sitzungsstatus\n", + "### Session status\n", "\n", - "* `panel.state` macht einige der internen Bokeh-Serverkomponenten für Benutzer verfügbar. \n", - "* `panel.state.curdoc` erlaubt den Zugriff auf das aktuelle [bokeh.document](https://bokeh.pydata.org/en/latest/docs/reference/document.html)." + "* `panel.state` exposes some of the internal Bokeh server components to users.\n", + "* `panel.state.curdoc` allows access to the current [bokeh.document](https://bokeh.pydata.org/en/latest/docs/reference/document.html)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Einbetten\n", + "## Embed\n", "\n", - "Panel benötigt im Allgemeinen entweder den Jupyter-Kernel oder einen Bokeh-Server, der im Hintergrund ausgeführt wird, um interaktives Verhalten zu ermöglichen. Für einfache Apps ist es jedoch auch möglich, den gesamten Widget-Status zu erfassen, sodass die App vollständig von Javascript aus verwendet werden kann. Um dies zu demonstrieren, erstellen wir eine einfache App, die einfach einen Schiebereglerwert annimmt, diesen mit 5 multipliziert und dann das Ergebnis anzeigt:" + "Panel generally needs either the Jupyter kernel or a Bokeh server running in the background to enable interactive behavior. However, for simple apps it is also possible to capture the entire widget status so that the app can be used entirely from Javascript. To demonstrate this, let’s create a simple app that simply takes a slider value, multiplies that by 5, and then displays the result:" ] }, { @@ -4885,26 +4885,26 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr das obige Widget ausprobieren, werdet ihr feststellen, dass es nur drei verschiedene Status hat, `0`, `5` und `10`. Dies liegt daran, dass beim Einbetten standardmäßig versucht wird, die Anzahl der Optionen für nicht-diskrete oder halb-diskrete Widgets auf höchstens drei Werte zu beschränken. Dies kann mit dem `max_opts`-Argument der `embed`-Methode verändert werden. Die vollständigen Optionen für die `embed`-Methode sind:\n", + "If you try the above widget, you will find that it only has three different status `0`, `5` and `10`. This is because embedding attempts to limit the number of options for non-discrete or semi-discrete widgets to a maximum of three values by default. This can be changed with the `max_opts` argument of the `embed` method. The full options for the `embed` method are:\n", "\n", - "* `max_states`: Maximale Anzahl der einzubettenden Zustände\n", - "* `max_opts`: Maximale Anzahl von Status für ein einzelnes Widget\n", - "* `json`: Gibt an, ob die Daten in json-Dateien exportiert werden sollen\n", - "* `save_path`: Pfad zum Speichern von JSON-Dateien (`default='./'`)\n", - "* `load_path`: Pfad oder URL, von dem bzw. der die JSON-Dateien geladen werden (wie `save_path` wenn nicht anders angegeben)\n", + "* `max_states`: Maximum number of states to be embedded\n", + "* `max_opts`: Maximum number of states for a single widget\n", + "* `json`: Specifies whether the data should be exported to json files\n", + "* `save_path`: Path to save JSON filesDateien (`default='./'`)\n", + "* `load_path`: Path or URL from which the JSON files are loaded (as `save_path` unless otherwise specified)\n", "\n", - "Wie ihr euch leicht vorstellen könnt, kann es bei mehreren Widgets schnell zu einer kombinatorischen Explosion der Status kommen, sodass die Ausgabe standardmäßig auf etwa 1000 Status beschränkt ist. Bei größeren Apps können die Status auch in JSON-Dateien exportiert werden. Wenn ihr die App beispielsweise auf einer Website bereitstellen möchtet, gebt mit `save_path` an, wo die JSON-Datei gespeichert werden soll und mit `load_path`, wo der JS-Code nach den Dateien suchen soll." + "As you can easily imagine, a combinatorial explosion of the statuses can quickly occur with several widgets, so that the output is limited to around 1000 statuses by default. For larger apps, the status can also be exported to JSON files. For example, if you want to make the app available on a website, specify `save_path` where the JSON file should be saved and `load_path` where the JS code should search for the files." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Speichern\n", + "## Save\n", "\n", - "Wenn Sie keinen tatsächlichen Server benötigen oder einfach einen statischen Snapshot einer Panel-App exportieren möchten, können Sie die saveMethode verwenden, mit der die App in eine eigenständige HTML- oder PNG-Datei exportiert werden kann.\n", + "If you don’t need an actual server or just want to export a static snapshot of a panel app, you can use the save method which can be used to export the app to a standalone HTML or PNG file.\n", "\n", - "Standardmäßig hängt die generierte HTML-Datei vom Laden des JavaScript-Codes für BokehJS aus dem Online- CDNRepository ab, um die Dateigröße zu verringern. Wenn Sie in einer Umgebung mit oder ohne Netzwerk arbeiten müssen, können Sie festlegen, dass INLINERessourcen anstelle von CDN:" + "By default, the generated HTML file depends on loading the JavaScript code for BokehJS from the online CDN repository to reduce the file size. If you need to work in a networked or non-networked environment, you can choose to use INLINE resources instead of CDN:" ] }, { @@ -4922,7 +4922,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Für den Export der `png`-Datei benötigt ihr zusätzlich Selenium und PhantomJS:\n", + "To export the `png` file you also need Selenium and PhantomJS:\n", "\n", " $ pipenv install selenium\n", " Installing selenium…\n", @@ -4933,13 +4933,13 @@ " + phantomjs-prebuilt@2.1.16\n", " added 81 packages from 76 contributors in 31.121s\n", "\n", - "Darüber hinaus könnt ihr mit der `save`-Methode z.B. auch die `embed`-Option aktivieren um die App-Status in die App einzubetten oder in JSON-Dateien zu speichern, die zusammen mit dem exportierten HTML-Code deployed werden können. U.a. habt ihr folgende Optionen:\n", + "In addition, you can use the `save` method together with the `embed` option to embed the app status in the app or to save it in JSON files, which can be deployed together with the exported HTML code. You have the following options:\n", "\n", - "* `resources`: `bokeh.resources`, z.B. `CDN` oder `INLINE`\n", - "* `embed`: Boolscher Wert, ob die Status in der Datei gespeichert werden sollen oder nicht.\n", - "* `max_states`: Die maximale Anzahl der einzubettenden Status\n", - "* `max_opts`: Die maximale Anzahl der Status für ein einzelnes Widget\n", - "* `embed_json`: Boolscher Wert, ob die Daten als JSON-Datei exportiert werden sollen (`default=True`).\n" + "* `resources`: `bokeh.resources`, e.g. `CDN` or `INLINE`\n", + "* `embed`: Boolean value, whether the status should be saved in the file or not.\n", + "* `max_states`: The maximum number of states to be embedded\n", + "* `max_opts`: The maximum number of states for a single widget\n", + "* `embed_json`: Boolean value as to whether the data should be exported as a JSON file (`default=True`)." ] } ], diff --git a/docs/web/dashboards/panel/index.rst b/docs/web/dashboards/panel/index.rst index 90e9d26b..e734cd07 100644 --- a/docs/web/dashboards/panel/index.rst +++ b/docs/web/dashboards/panel/index.rst @@ -1,11 +1,10 @@ Panel ===== -`Panel `_ wurde auf Basis von `Bokeh -`_ und `Param -`_ entwickelt und bietet ein Toolkit speziell -zur Erstellung von Apps und Dashboards, das jedoch nicht nur Bokeh-Plots -unterstützt. +`Panel `_ was developed on the basis of `Bokeh +`_ and `Param +`_ and offers a toolkit especially for creating +apps and dashboards, which not only supports bokeh plots. .. seealso:: * `Panel Announcement `_ diff --git a/docs/web/dashboards/panel/install.rst b/docs/web/dashboards/panel/install.rst index 0c4036cc..8c960206 100644 --- a/docs/web/dashboards/panel/install.rst +++ b/docs/web/dashboards/panel/install.rst @@ -1,8 +1,7 @@ Installation ============ -Ihr könnt Panel in der virtuellen Umgebung eurer Jupyter-Kernels installieren -mit: +You can install Panel in the virtual environment of your Jupyter kernel with: .. code-block:: console @@ -14,9 +13,9 @@ mit: Successfully installed bokeh-1.3.4 markdown-3.1.1 panel-0.6.2 param-1.9.1 pyct-0.4.6 pyviz-comms-0.7.2 … -Für einige der folgenden Beispiele werden zusätzliche Pakete benötigt wie -z.B. `Holoviews `_ und `hvPlot -`_. Sie können installiert werden mit: +For some of the following examples additional packages are required such as +`Holoviews `_ and `hvPlot +`_. They can be installed with: .. code-block:: console @@ -34,20 +33,19 @@ z.B. `Holoviews `_ und `hvPlot Successfully installed hvplot-0.4.0 … -Beispiele ---------- +Examples +-------- -#. Herunterladen +#. Download .. code-block:: console $ pipenv run panel examples Copied examples to /Users/veit/jupyter-tutorial/panel-examples -#. Betrachten +#. View - Anschließend könnt ihr euch die Beispiele anschauen, z.B. - ``Introduction.ipynb`` mit + Then you can look at the examples, for example ``Introduction.ipynb`` with .. code-block:: console diff --git a/docs/web/dashboards/panel/interact.ipynb b/docs/web/dashboards/panel/interact.ipynb index dd4c6119..a3535df4 100644 --- a/docs/web/dashboards/panel/interact.ipynb +++ b/docs/web/dashboards/panel/interact.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Interaktionen\n", + "# Interactions\n", "\n", - "Die `interact`-Funktion `(panel.interact)` erstellt automatisch Steuerelemente zum interaktiven Durchsuchen von Code und Daten." + "The `interact` function `(panel.interact)` automatically creates controls for interactively browsing code and data." ] }, { @@ -1368,7 +1368,7 @@ "source": [ "## `interact`\n", "\n", - "Auf der einfachsten Ebene werden `interact`-Steuerelemente für Funktionsargumente automatisch generiert und die Funktion dann mit diesen Argumenten aufgerufen, wenn ihr die Steuerelemente interaktiv bearbeitet. Zur Verwendung von `interact` müsst ihr eine Funktion definieren, die ihr untersuchen möchtet. Hier ist eine Funktion, die das einzige Argument ausgibt: `x`." + "At the simplest level, `interact` controls are automatically generated for function arguments, and the function is then called with those arguments when you interactively edit the controls. To use `interact` you need to define a function that you want to examine. Here is a function that returns the only argument: `x`." ] }, { @@ -1385,7 +1385,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr diese Funktion als erstes Argument zusammen mit einem ganzzahligen Schlüsselwortargument `x=10` an `interact` übergebt, wird ein Schieberegler generiert und an den Funktionsparameter gebunden." + "If you pass this function as the first argument together with an integer keyword argument `x=10` to `interact` a slider is generated and bound to the function parameters." ] }, { @@ -1504,9 +1504,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr den Schieberegler bewegt, wird die Funktion aufgerufen, die den aktuellen Wert von `x` ausgibt.\n", - "\n", - "Wenn ihr `True` oder `False` übergebt, generiert `interact` ein Kontrollkästchen:" + "If you move the slider, the function is called, which outputs the current value of `x`.\n", + "If you pass `True` or `False` `interact` generates a check box:" ] }, { @@ -1625,7 +1624,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr eine Zeichenfolge übergebt, generiert `interact` ein Textbereich." + "When you pass a string, `interact` generates a text area." ] }, { @@ -1744,7 +1743,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`interact` kann auch als *Decorator* verwendet werden. Auf diese Weise könnt ihr sowohl eine Funktion definieren als auch die Art der Interaktion festlegen. Wie das folgende Beispiel zeigt, funktioniert `interact` auch mit Funktionen, die mehrere Argumente haben." + "`interact` can also be used as a *Decorator*. In this way you can define a function as well as determine the type of interaction. As the following example shows, `interact` works also with functions that have multiple arguments." ] }, { @@ -1867,9 +1866,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Layout interaktiver Widgets\n", + "## Layout of interactive widgets\n", "\n", - "Die `interact`-Funktion gibt ein Panel zurück, das die Widgets und die Anzeigeausgabe enthält. Durch Indizieren dieser Panel können wir das Layout für die Objekte genau so festlegen, wie wir wollen:" + "The `interact` function returns a panel that contains the widgets and the display output. By indexing these panels we can lay out the objects exactly how we want:" ] }, { @@ -2127,9 +2126,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Argumente festlegen mit `fixed`\n", + "## Set arguments with `fixed`\n", "\n", - "Es kann vorkommen, dass ihr eine Funktion mithilfe von `interact` untersuchen möchtet, aber eines oder mehrere ihrer Argumente auf bestimmte Werte festlegen möchtet. Dies kann durch die `fixed`-Funktion erreicht werden:" + "There may be times when you want to examine a function using `interact`, but want to set one or more of its arguments to specific values. This can be achieved using the `fixed` function:" ] }, { @@ -2258,9 +2257,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## *Widget Abbreviations*\n", + "## *Widget abbreviations*\n", "\n", - "Wenn ihr bestimmte Werte übergebt, verwendet `interact` automatisch das passende Widget, z.B. eine Checkbox für `True` oder den `IntSlider` für ganzzahlige Werte. Ihr müsst also nicht explizit das passende Widget angeben:" + "If you pass certain values, `interact` use automatically the appropriate widget, e.g. a checkbox for `True` or `IntSlider` for integer values. So you don’t have to explicitly specify the appropriate widget:" ] }, { @@ -2491,20 +2490,20 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dieses Beispiel verdeutlicht, wie `interact` die Schlüsselwortargumente verarbeitet werden:\n", + "This example shows how the keyword arguments are processed by `interact`:\n", "\n", - "1. Wenn das Schlüsselwortargument eine `Widget`-Instanz mit einem `value`-Attribut ist, wird dieses Widget verwendet. Dabei kann jedes Widget mit einem `value`-Attribut verwendet werden, auch benutzerdefinierte.\n", - "2. Andernfalls wird der Wert als *Widget Abbreviation* behandelt, die vor der Verwendung in ein Widget konvertiert wird.\n", + "1. If the keyword argument is an instance of `Widget` with an `value` attribute, this widget is used. Any widget with an `value` attribute can be used, including custom ones.\n", + "2. Otherwise, the value is treated as a *Widget Abbreviation* that is converted to a widget before use.\n", "\n", - "Die folgende Tabelle gibt einen Überblick über verschiedene *Widget Abbreviations*:\n", + "The following table gives an overview of the various *Widget Abbreviations*:\n", "\n", "| Keyword argument | Widget |\n", "|:----------------------------------------------------|:--------------|\n", - "| `True` oder `False` | `Checkbox` |\n", + "| `True` or `False` | `Checkbox` |\n", "| `'Hi Pythonistas!'` | `Text` |\n", - "| Ganzzahliger Wert als `min`, `max`,`step`, `value` | `IntSlider` |\n", - "| Gleitkommazahl als `min`, `max`,`step`, `value` | `FloatSlider` |\n", - "| `['apple','pear']` oder `{'one':1,'two':2}` | `Dropdown` |" + "| Integer value as `min`, `max`,`step`, `value` | `IntSlider` |\n", + "| Floating-point `min`, `max`,`step`, `value` | `FloatSlider` |\n", + "| `['apple','pear']` or `{'one':1,'two':2}` | `Dropdown` |" ] } ], diff --git a/docs/web/dashboards/panel/overview.ipynb b/docs/web/dashboards/panel/overview.ipynb index 7e714b07..0e3a9120 100644 --- a/docs/web/dashboards/panel/overview.ipynb +++ b/docs/web/dashboards/panel/overview.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Überblick\n", + "# Overview\n", "\n", - "In einem Panel könnt ihr interaktive Steuerelemente hinzufügen. Dies erlaubt euch, einfache interaktive Apps, aber auch komplexe mehrseitige Dashboards zu erstellen.Wir beginnen zunächst mit einem einfachen Beispiel einer Funktion zum Zeichnen einer Sinuswelle mit Matplotlib:" + "You can add interactive controls in a panel. This allows you to create simple interactive apps, but also complex multi-page dashboards. We’ll start with a simple example of a function for drawing a sine wave with Matplotlib:" ] }, { @@ -48,9 +48,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Interaktive Panels\n", + "## Interactive panels\n", "\n", - "Wenn wir viele Kombinationen dieser Werte ausprobieren möchten, um zu verstehen, wie sich Frequenz und Amplitude auf dieses Diagramm auswirken, könnten wir die oben genannte Zelle viele Male neu bewerten. Dies wäre jedoch ein langsamer und aufwändiger Prozess. Stattdessen die Werte im Code jedesmal neu angeben zu müssen, empfiehlt sich, die Werte mithilfe von Schiebereglern interaktiv anzupassen. Mit einer solchen Panel-App könnt ihr einfach die Parameter einer Funktion untersuchen. Dabei ähnelt `pn.interact` der Funktion von [ipywidgets interact](https://ipywidgets.readthedocs.io/en/stable/examples/Using%20Interact.html):" + "If we wanted to try many combinations of these values to understand how frequency and amplitude affect this graph, we could reevaluate the above cell many times. However, this would be a slow and tedious process. Instead of having to re-enter the values in the code each time, it is advisable to adjust the values interactively with the help of sliders. With such a panel app you can easily examine the parameters of a function. The function of `pn.interact` is similar to [ipywidgets interact](https://ipywidgets.readthedocs.io/en/stable/examples/Using%20Interact.html):" ] }, { @@ -1512,16 +1512,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Solange ein Live-Python-Prozess ausgeführt wird, wird durch Ziehen dieser Widgets die `sine`-Callback-Funktion aufgerufen und auf die von euch ausgewählte Kombination von Parameterwerten ausgewertet und die Ergebnisse angezeigt. Mit einem solchen Panel könn ihr einfach alle Funktionen untersuchen, die ein visuelles Ergebnis eines unterstützten Objekttyps (s. [Supported object types and libraries](https://github.com/pyviz/panel/issues/2) liefern, z.B. Matplotlib, Bokeh, Plotly, Altair oder verschiedene Text- und Bildtypen." + "As long as a live Python process is running, dragging these widgets calls the `sine` callback function and evaluates the combination of parameter values ​​you selected and displays the results. With such a panel you can easily examine all functions that provide a visual result of a supported object type (see [Supported object types and libraries](https://github.com/pyviz/panel/issues/2), e.g. Matplotlib, Bokeh, Plotly, Altair or various text and image types." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Komponenten von Panels \n", + "## Components of panels \n", "\n", - "`interact` ist praktisch, aber was ist, wenn Sie mehr Kontrolle darüber wünschen, wie es aussieht oder funktioniert? Lassen Sie uns zunächst sehen, was `interact` tatsächlich erstellt wird, indem Sie das Objekt greifen und seine Darstellung anzeigen:" + "`interact` is handy, but what if you want more control over how it looks or works? First, let’s see what `interact` is actually created by grabbing the object and viewing its representation:" ] }, { @@ -1552,7 +1552,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir sehen hier, dass der `interact`-Aufruf ein `pn.Column`-Objekt erstellt hat, das aus einer WidgetBox (mit 3 Widgets) und einer `pn.Row`-Matplotlib-Figure besteht. Das Bedienfeld ist kompositorisch, sodass ihr diese Komponenten beliebig mischen und zuordnen könnt, indem ihr bei Bedarf weitere Objekte hinzufügt:" + "We can see here that the `interact` call has created an `pn.Column` object that consists of a WidgetBox (with 3 widgets) and a `pn.Row` Matplotlib figure. The control panel is compositional, so you can mix and match these components as you like by adding as many objects as needed:" ] }, { @@ -1672,7 +1672,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Beachtet, dass die Widgets mit ihrem Plot verknüpft bleiben, auch wenn sie sich in einer anderen Notebook-Zelle befinden:" + "Note that the widgets remain linked to their plot, even if they are in a different notebook cell:" ] }, { @@ -1787,18 +1787,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Neue Panels\n", + "## New panels\n", "\n", - "Mit diesem kompositorischen Ansatz könnt ihr verschiedene Komponenten wie Widgets, Diagramme, Text und andere Elemente, die für eine App oder ein Dashboard benötigt werden, auf beliebige Weise kombinieren. Das `interact`-Beispiel baut auf einem reaktiven Programmiermodell auf, bei dem sich eine Eingabe für die Funktion ändert und das Bedienfeld die Ausgabe der Funktion reaktiv aktualisiert. `interact` ist eine praktische Möglichkeit, Widgets aus den Argumenten für Ihre Funktion automatisch zu erstellen. Panel bietet jedoch auch eine explizitere reaktive API, mit der ihr Verbindungen zwischen Widgets und Funktionsargumenten definieren und anschließend das resultierende Dashboard manuell von Grund auf neu erstellen können.\n", + "With this compositional approach, you can combine different components such as widgets, charts, text and other elements that are needed for an app or a dashboard in any way you want. The `interact` example is based on a reactive programming model in which an input for the function changes and the control panel reactively updates the output of the function. `interact` is a handy way to automatically build widgets from the arguments for your function. However, Panel also provides a more explicit reactive API that allows you to define connections between widgets and function arguments, and then manually create the resulting dashboard from scratch.\n", "\n", - "Im folgenden Beispiel deklarieren wir explizit jede Komponente einer App: \n", + "In the following example we explicitly declare every component of an app:\n", "\n", "1. Widgets\n", - "2. eine Funktion zum Berechnen von Sinuswerten\n", - "3. Spalten- und Zeilencontainer\n", - "4. die fertige `sine_panel`-App.\n", + "2. a function for calculating sine values\n", + "3. Column and row containers\n", + "4. the finished `sine_panel` app.\n", "\n", - "Widget-Objekte haben mehrere Parameter (aktueller Wert, zulässige Bereiche usw.), und hier verwenden wir den `depends`-Decorator von Panel, um zu deklarieren, dass die Eingabewerte der Funktion von den `value`-Parametern der Widgets stammen sollen. Wenn nun die Funktion und die Widgets angezeigt werden, aktualisiert das Panel die angezeigte Ausgabe automatisch, wenn sich eine der Eingaben ändert:" + "Widget objects have several parameters (current value, allowed ranges, etc.), and here we use the `depends` Panel decorator to declare that the input values of the function should come from the `value` parameters of the widgets. Now, when the function and widgets are displayed, the panel automatically updates the displayed output if one of the inputs changes:" ] }, { @@ -1930,9 +1930,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Deploy-Panels\n", + "## Deploy panels\n", "\n", - "Die obigen Panels funktionieren alle in einer Notebook-Zelle, aber im Gegensatz zu `ipywidgets` und anderen Ansätzen funktionieren `Panel`-Apps auch auf eigenständigen Servern. Die obige App kann beispielsweise als eigener Webserver gestartet werden, mit:" + "The above panels all work in a notebook cell, but unlike `ipywidgets` and other approaches, `Panel` apps work on standalone servers as well. The above app can, for example, be started as a separate web server with:" ] }, { @@ -1959,9 +1959,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dies startet den Bokeh-Server und öffnet ein Browser-Fenster mit der Anwendung.\n", + "This will start the Bokeh server and open a browser window with the application.\n", "\n", - "Oder ihr könnt einfach angeben, was ihr auf der Webseite sehen möchtet. `servable()`, und dann den Shell-Befehl `pipenv run panel serve --show example.ipynb`, um einen Server mit diesem Objekt zu starten:" + "Or you can just indicate what you want to see on the website. `servable()`, and then the shell command to start a server with this object `pipenv run panel serve --show example.ipynb`:" ] }, { @@ -1977,18 +1977,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Semikolon vermeidet, dass hier im Notizbuch eine weitere Kopie des Sinusfelds angezeigt wird." + "The semicolon prevents another copy of the sine field from being displayed here in the notebook." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Deklarative Panels\n", + "## Declarative Panels\n", "\n", - "Der obige Kompositionsansatz ist sehr flexibel, verknüpft jedoch domänenspezifischen Code (die Teile über Sinuswellen) mit dem Widget-Anzeigecode. Das ist üblich in prototypischen Projekten, aber in Projekten, bei denen der Code in vielen verschiedenen Kontexten verwendet werden soll, sollen Teile des Codes, die sich auf die zugrunde liegende Domänen (d.h. die Anwendung oder den Forschungsbereich) beziehen, von denen getrennt werden, die an bestimmte Anzeigetechnologien gebunden sind (wie Jupyter-Notebooks oder Webserver).\n", + "The above compositional approach is very flexible, but it links domain-specific code (the parts about sine waves) to the widget display code. This is common in prototypical projects, but in projects where the code is going to be used in many different contexts, parts of the code that relate to the underlying domains (i.e. the application or research area) should be separated from those that are tied to certain display technologies (such as Jupyter notebooks or web servers).\n", "\n", - "Für solche Verwendungen unterstützt Panel Objekte, die mit der separaten [Param](http://param.pyviz.org/)-Bibliothek deklariert wurden. Dies bietet eine Möglichkeit, die Parameter eurer Objekte (Code, Parameter, Anwendung und Dashboard-Technologie) unabhängig zu erfassen und zu deklarieren. Der obige Code kann zum Beispiel in einem Objekt erfasst werden, das die Bereiche und Werte aller Parameter sowie die Generierung des Diagramms unabhängig von der Panel-Bibliothek oder einer anderen Art der Interaktion mit dem Objekt deklariert:" + "For such uses, Panel supports objects that have been declared with the separate [Param](http://param.pyviz.org/) library. This offers a possibility to independently record and declare the parameters of your objects (code, parameters, application and dashboard technology). For example, the above code can be captured in an object that declares the ranges and values of all parameters as well as the generation of the diagram independently of the panel library or any other type of interaction with the object:" ] }, { @@ -2014,7 +2014,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die `Sine`-Klasse und die `sine_obj`-Instanz sind nicht abhängig von Panel, Jupyter oder einem anderen GUI- oder Web-Toolkit – sie deklarieren einfach Fakten über eine bestimmte Domäne (z.B., dass Sinuswellen Frequenz- und Amplitudenparameter annehmen und dass die Amplitude eine Zahl größer oder gleich Null ist). Diese Informationen reichen dann für Panel aus, um eine bearbeitbare und anzeigbare Darstellung für dieses Objekt zu erstellen, ohne dass etwas angegeben werden muss, das von den domänenspezifischen Details abhängt, die in Die `Sine`-Klasse und die `sine_obj`-Instanz sind nicht abhängig von Panel, Jupyter oder einem anderen GUI- oder Web-Toolkit. Sie deklarieren einfach Fakten über einen bestimmten Bereich (z. B., dass Sinuswellen Frequenz- und Amplitudenparameter annehmen und dass die Amplitude eine Zahl größer oder gleich Null ist). Diese Informationen reichen dann für Panel aus, um eine bearbeitbare und anzeigbare Darstellung für dieses Objekt zu erstellen, ohne dass etwas angegeben werden muss, das von den domänenspezifischen Details abhängt, die außerhalb von `sine_obj` enthalten sind:" + "The `Sine` class and `sine_obj` instance are not dependent on Panel, Jupyter or any other GUI or web toolkit – they simply declare facts about a particular domain (e.g. that sine waves take frequency and amplitude parameters and that the amplitude is a number greater or equals zero). That information is then enough for Panel to create an editable and viewable representation for this object without having to specify anything that depends on the domain-specific details contained in the `Sine` class and the `sine_obj` -Instance are not dependent on Panel, Jupyter or any other GUI or web toolkit. They simply declare facts about a certain range (e.g., that sine waves take frequency and amplitude parameters, and that the amplitude is a number greater than or equal to zero). That information is enough for Panel to create an editable and viewable representation for this object without having to specify anything that depends on the domain-specific details contained outside of `sine_obj`:" ] }, { @@ -2135,18 +2135,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Um eine bestimmte Domäne zu unterstützen, könnt ihr Hierarchien solcher Klassen erstellen, in denen alle Parameter und Funktionen zusammengefasst sind, die ihr für verschiedene Objektfamilien benötigt. Dabei werden sowohl Parameter als auch Code in den Klassen übernommen, und zwar unabhängig von einer bestimmten GUI-Bibliothek oder sogar das Vorhandensein einer GUI überhaupt. Dieser Ansatz macht es praktisch, eine große Codebasis beizubehalten, die mit Panel vollständig angezeigt und bearbeitet werden kann, und zwar auf eine Weise, die im Laufe der Zeit beibehalten und angepasst werden kann." + "In order to support a certain domain, you can create hierarchies of such classes, in which all parameters and functions are summarised that you need for different object families. Both parameters and code are adopted in the classes, regardless of a specific GUI library or even the existence of a GUI at all. This approach makes it convenient to maintain a large code base that can be fully viewed and edited with Panel, in a way that can be maintained and customised over time." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Verknüpfen von Plots und Aktionen zwischen Panels\n", + "## Linking plots and actions between panels\n", "\n", - "Die oben genannten Ansätze arbeiten jeweils mit einer Vielzahl von anzeigbaren Objekten, einschließlich Bildern, Gleichungen, Tabellen und Diagrammen. In jedem Fall bietet das Panel interaktive Funktionen mithilfe von Widgets und aktualisiert die angezeigten Objekte entsprechend, wobei nur sehr wenige Annahmen darüber getroffen werden, was tatsächlich angezeigt wird. Panel unterstützt auch eine umfassendere und dynamischere Interaktivität, bei der das angezeigte Objekt selbst interaktiv ist, z.B. JavaScript-basierte Diagramme von Bokeh und Plotly.\n", + "The above approaches each work with a variety of displayable objects, including images, equations, tables, and charts. In each case, the panel provides interactive functionality using widgets and updates the objects displayed accordingly, making very few assumptions about what is actually displayed. Panel also supports a broader and more dynamic interactivity in which the displayed object itself is interactive, e.g. JavaScript-based diagrams of Bokeh and Plotly.\n", "\n", - "Wenn wir beispielsweise den mit Pandas gelieferten Matplotlib-Wrapper durch den[Bokeh](http://bokeh.pydata.org/)-Wrapper [hvPlot](http://hvplot.pyviz.org/) ersetzen, erhalten wir automatisch interaktive Plots, die *zooming*, *panning* und *hovering* ermöglichen:" + "For example, if we replace the matplotlib wrapper that came with pandas with the [Bokeh](http://bokeh.pydata.org/) wrapper [hvPlot](http://hvplot.pyviz.org/), we automatically get interactive plots that allow *zooming*, *panning* und *hovering*:" ] }, { @@ -4506,7 +4506,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Diese interaktiven Aktionen können mit komplexeren Interaktionen in einem Plot (z. B. `tap`, `hover`) kombiniert werden um das Erkunden von Daten und das Aufdecken von Zusammenhängen zu vereinfachen. Beispielsweise können wir HoloViews verwenden, um eine umfassendere Version des hvPlot-Beispiels zu erstellen, das dynamisch aktualisiert wird um die Position auf dem Kreis anzuzeigen, wenn wir mit der Maus über die Sinuskurve fahren:" + "These interactive actions can be combined with more complex interactions in a plot (e.g. `tap`, `hover`) to make it easier to explore data and uncover connections. For example, we can use HoloViews to create a more comprehensive version of the hvPlot example that is dynamically updated to show the position on the circle as we hover over the sine curve:" ] }, { diff --git a/docs/web/dashboards/panel/params.ipynb b/docs/web/dashboards/panel/params.ipynb index 5c730fb2..00ed87be 100644 --- a/docs/web/dashboards/panel/params.ipynb +++ b/docs/web/dashboards/panel/params.ipynb @@ -4,20 +4,20 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Parametrisierung\n", + "# Parameterisation\n", "\n", - "Panel unterstützt die Verwendung von Parametern und Abhängigkeiten zwischen Parametern, die von [param](https://github.com/ioam/param) in einfacher Weise ausgedrückt werden, um Dashboards als deklarative, eigenständige Klassen zu kapseln.\n", + "Panel supports the use of parameters and dependencies between parameters, expressed in a simple way by [param](https://github.com/ioam/param), to encapsulate dashboards as declarative, stand-alone classes.\n", "\n", - "Parameter sind Python-Attribute, die mithilfe der `param`-Bibliothek erweitert wurden, um Typen, Bereiche und Dokumentation zu unterstützen. Dabei handelt es sich lediglich um die Informationen, die ihr zum automatischen Erstellen von Widgets für jeden Parameter benötigt." + "Parameters are Python attributes that have been extended using the `param` library to support types, ranges, and documentation. This is just the information you need to automatically create widgets for each parameter." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Parameter und Widgets\n", + "## Parameters and widgets\n", "\n", - "Hierfür werden zuerst einige parametrisierte Klassen mit verschiedenen Parametern deklariert:" + "For this purpose, some parameterised classes with different parameters are declared first:" ] }, { @@ -77,13 +77,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wie ihr seht, hängt die Deklaration von Parametern nur von der separaten `param`-Bibliothek ab. Parameter sind eine einfache Idee mit einigen Eigenschaften, die für die Erstellung von sauberem, verwendbarem Code entscheidend sind:\n", + "As you can see, the declaration of parameters only depends on the separate `param` library. Parameters are a simple idea with a few properties critical to creating clean, usable code:\n", "\n", - "* Die `param`-Bibliothek ist in reinem Python ohne Abhängigkeiten geschrieben, wodurch es einfach ist, sie in jeden Code einzubinden, ohne sie an eine bestimmte GUI- oder Widgets-Bibliothek oder an Jupyter-Notebooks zu binden.\n", - "* Parameterdeklarationen konzentrieren sich auf semantische Informationen, die für eure Domäne relevant sind. So vermeidet ihr, dass domänenspezifischer Code durch irgendetwas verunreinigt wird, das ihn an eine bestimmte Art der Anzeige oder Interaktion mit ihm bindet.\n", - "* Parameter können überall dort definiert werden, wo sie in Ihrer Vererbungshierarchie sinnvoll sind, und ihr könnt sie einmal dokumentieren, eingeben und auf einen bestimmten Bereich beschränken. Dabei werden alle diese Eigenschaften von einer beliebigen Basisklasse geerbt. Beispielsweise funktionieren hier alle Parameter gleich, unabhängig davon, ob sie in `BaseClass` oder `Example` deklariert wurden. Dies erleichtert die einmalige Bereitstellung dieser Metadaten und verhindert, dass sie überall im Code dupliziert werden, wo Bereiche oder Typen überprüft oder Dokumentationen gespeichert werden müssen.\n", + "* The `param` library is written in pure Python with no dependencies, which makes it easy to include in any code without tying it to a specific GUI or widgets library, or to Jupyter notebooks.\n", + "* Parameter declarations focus on semantic information that is relevant to your domain. In this way, you avoid contaminating domain-specific code with anything that binds it to a specific display or interaction with it.\n", + "* Parameters can be defined wherever they make sense in your inheritance hierarchy, and you can document them once, enter them and limit them to a certain area. All these properties are inherited from any base class. For example, all parameters work the same here, regardless of whether they were declared in `BaseClass` or `Example`. This makes it easier to provide this metadata once and prevents it from being duplicated anywhere in the code where areas or types need to be checked or documentation saved.\n", "\n", - "Wenn ihr euch dann für die Verwendung dieser parametrisierten Klassen in einer Notebook- oder Webserverumgebung entscheidet, könnt ihr mit `import panel` die Parameterwerte als optionalen zusätzlichen Schritt einfach anzeigen und bearbeiten:" + "If you then decide to use these parameterised classes in a notebook or web server environment, you can easily display and edit the parameter values as an optional additional step with `import panel`:" ] }, { @@ -1578,11 +1578,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wie ihr seht, muss Panel nicht über Kenntnisse Ihrer domänenspezifischen Anwendung verfügen, auch nicht über die Namen eurer Parameter. Es werden einfach Widgets für alle Parameter angezeigt, die für dieses Objekt definiert wurden. Durch die Verwendung von Param mit Panel wird somit eine nahezu vollständige Trennung zwischen eurem domänenspezifischen Code und eurem Display-Code erreicht, wodurch die Wartung beider über einen längeren Zeitraum erheblich vereinfacht wird. Hier wurde sogar das `msg`-Behavior der Schaltflächen deklarativ festgelegt als eine Aktion, die unabhängig davon, ob sie in einer GUI oder in einem anderen Kontext verwendet wird, aufgerufen werden kann.\n", + "As you can see, Panel does not need to have knowledge of your domain-specific application, nor of the names of your parameters. It simply shows widgets for all parameters that have been defined for this object. By using Param with Panel, an almost complete separation between your domain-specific code and your display code is achieved, which considerably simplifies the maintenance of both over a longer period of time. Here even the `msg` behavior of the buttons was declared declaratively as an action that can be called regardless of whether it is used in a GUI or in another context.\n", "\n", - "Die Interaktion mit den oben genannten Widgets wird nur im Notebook und auf dem Bokeh-Server unterstützt. Ihr könnt jedoch auch statische Renderings der Widgets in eine Datei oder eine Webseite exportieren.\n", + "Interaction with the above widgets is only supported in the notebook and on the bokeh server. However, you can also export static renderings of the widgets to a file or a website.\n", "\n", - "Wenn ihr Werte auf diese Weise bearbeitet, müsst ihr das Notebook standardmäßig Zelle für Zelle ausführen. Wenn ihr zu der obigen Zelle gelangt, bearbeitet ihr die Werte nach euren Wünschen und führt die nachfolgenden Zellen aus, in denen auf diese Parameterwerte verwiesen wird, werden eure interaktiv ausgewählte Einstellungen verwendet:" + "If you edit values in this way, you have to run the notebook cell by cell by default. When you get to the cell above, edit the values as you wish and execute the following cells, in which these parameter values are referred to, your interactively selected settings are used:" ] }, { @@ -1629,7 +1629,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Um dies zu umgehen und automatisch alle Widgets zu aktualisieren, die aus dem Parameter generiert wurden, könnt ihr das `param`-Objekt übergeben:" + "To work around this and automatically update all widgets generated from the parameter, you can pass the `param` object:" ] }, { @@ -1746,11 +1746,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Benutzerdefinierte Widgets \n", + "## Custom widgets\n", "\n", - "Im vorherigen Abschnitt haben wir gesehen, wie Parameter automatisch in Widgets umgewandelt werden können. Dies ist möglich, da Panel intern eine Zuordnung zwischen Parametertypen und Widget-Typen verwaltet. Manchmal bietet das Standard-Widget jedoch nicht die bequemste Benutzeroberfläche, und wir möchten Panel einen expliziten Hinweis geben, wie ein Parameter gerendert werden soll. Dies ist mit dem `widgets`-Argument für das `Param`-Panel möglich. Mit dem `widgets`-Keyword können wir eine Zuordnung zwischen dem Parameternamen und dem gewünschten Widget-Typ deklarieren.\n", + "In the previous section we saw how parameters can be automatically converted into widgets. This is possible because the Panel internally manages an assignment between parameter types and widget types. However, sometimes the standard widget doesn’t provide the most convenient user interface, and we want to give Panel an explicit hint on how a parameter should be rendered. This is possible with the `widgets` argument for the `Param` panel. With the `widgets` keyword we can declare an association between the parameter name and the desired widget type.\n", "\n", - "Als Beispiel können wir einer `RadioButtonGroup` und einem `DiscretePlayer` einen `String`- und einen `Number`-Selector zuordnen." + "As an example we can assign a `RadioButtonGroup` and a `DiscretePlayer` to a `String` and a `Number` selector." ] }, { @@ -1874,7 +1874,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Es ist auch möglich, Argumente an das Widget zu übergeben, um es anzupassen. Anstatt das Widget zu übergeben, übergebt ein Wörterbuch mit den gewünschten Optionen. Verwendet das `type`-Schlüsselwort, um das Widget zuzuordnen:" + "It is also possible to pass arguments to the widget to customise it. Instead of passing the widget, pass a dictionary with the options you want. Uses the `type` keyword to map the widget:" ] }, { @@ -1992,11 +1992,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Parameterabhängigkeiten\n", + "## Parameter dependencies\n", "\n", - "Das Deklarieren von Parametern ist normalerweise nur der Anfang eines Workflows. In den meisten Anwendungen sind diese Parameter dann an eine Berechnung gebunden. Um die Beziehung zwischen einer Berechnung und den Parametern, von denen sie abhängt, auszudrücken, kann der `param.depends`-Dekorator für parametrisierte Methoden verwendet werden. Dieser Dekorator gibt Panel und anderen `param`-basierten Bibliotheken (z.B. HoloViews) einen Hinweis, dass die Methode bei einer Änderung eines Parameters neu bewertet werden sollte.\n", + "Declaring parameters is usually just the beginning of a workflow. In most applications, these parameters are then linked to a computation. To express the relationship between a computation and the parameters on which it depends, the\n", + "`param.depends` decorator for parameterized methods can be used. This decorator gives panels and other `param`-based libraries (e.g. HoloViews) an indication that the method should be recalculated if a parameter is changed.\n", "\n", - "Als einfaches Beispiel ohne zusätzliche Abhängigkeiten schreiben wir eine kleine Klasse, die eine ASCII-Darstellung einer Sinuswelle zurückgibt, die von `phase` und `frequency`-Parametern abhängt. Wenn wir die `.view`-Methode an ein Panel übergeben wird die Ansicht automatisch neu berechnet und aktualisiert, sobald sich einer oder mehrere der Parameter ändern:" + "As a simple example with no additional dependencies, let's write a small class that returns an ASCII representation of a sine wave that depends on `phase` and `frequency` parameters. When we pass the `.view` method to a panel, the view is automatically recalculated and updated as soon as one or more of the parameters change:" ] }, { @@ -2131,9 +2132,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die parametrisierte und mit Anmerkungen versehene `view`-Methode kann einen beliebigen Typ zurückgeben, der vom [Pane-Objects](https://panel.pyviz.org/user_guide/Components.html#Panes)-Panel bereitgestellt wird. Auf diese Weise können Parameter und die zugehörigen Widgets auf einfache Weise mit einem Plot oder einer anderen Ausgabe verknüpft werden. Parametrisierte Klassen können daher ein sehr nützliches Muster sein, um einen Teil eines Rechenworkflows mit einer zugehörigen Visualisierung zu kapseln und die Abhängigkeiten zwischen den Parametern und der Berechnung deklarativ auszudrücken.\n", + "The parameterised and annotated `view` method can return any type provided by the [Pane-Objects](https://panel.pyviz.org/user_guide/Components.html#Panes) panel. This makes it easy to link parameters and their associated widgets to a plot or other output. Parameterised classes can therefore be a very useful pattern for encapsulating part of a computational workflow with an associated visualisation and for declaratively expressing the dependencies between the parameters and the computation.\n", "\n", - "Standardmäßig zeigt ein Param-Bereich (*Pane*) Widgets für alle Parameter mit einem `precedence`-Wert über dem Wert `pn.Param.display_threshold` an, sodass ihr `precedence` verwenden könnt um automatisch Parameter auszublenden. Ihr könnt auch explizit auswählen, welche Parameter Widgets in einem bestimmten Beriech enthalten sollen, indem ihr ein `parameters`-Argument übergebt. Dieser Code gibt beispielsweise ein `phase`-Widget aus wobei `sine.frequency` den Anfangswert `1` beibehält:" + "By default, a Param area (*Pane*) shows widgets for all parameters with a `precedence` value above the value `pn.Param.display_threshold`, so you can use `precedence` to automatically hide parameters. You can also explicitly choose which parameters should contain widgets in a certain area by passing an `parameters` argument. For example, this code outputs a `phase` widget, keeping `sine.frequency` the initial value `1`:" ] }, { @@ -2252,9 +2253,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Ein weiteres gängiges Muster ist das Verknüpfen der Werte eines Parameters mit einem anderen Parameter, z.B. wenn Abhängigkeiten zwischen Parametern bestehen. Im folgenden Beispiel definieren wir zwei Parameter, einen für den Kontinent und einen für das Land. Da wir möchten, dass sich die Auswahl der gültigen Länder ändert, wenn wir den Kontinent wechseln, definieren wir eine Methode, um dies für uns zu tun. Um die beiden zu verbinden, drücken wir die Abhängigkeit mithilfe des `param.depends`-Dekorators aus und stellen dann mit `watch=True` sicher, dass die Methode ausgeführt wird, wenn der Kontinent geändert wird.\n", + "Another common pattern is linking the values of one parameter to another parameter, for example when there are dependencies between parameters. In the following example we define two parameters, one for the continent and one for the country. Since we would like the selection of valid countries to change when we change continent, let’s define a method to do this for us. To connect the two, we express the dependency using the `param.depends` decorator and then use `watch=True` to ensure that the method is executed when the continent is changed.\n", "\n", - "Wir definieren auch eine `view`-Methode, die einen HTML-Iframe zurückgibt, der das Land mithilfe von Google Maps anzeigt." + "We also define a `view` method that returns an HTML iframe showing the country using Google Maps." ] }, { @@ -2399,7 +2400,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Immer wenn sich der Kontinent ändert, wird nun die `_update_countries`-Methode zum Ändern der angezeigten Länderliste ausgeführt, was wiederum eine Aktualisierung der `view`-Methode auslöst." + "Whenever the continent changes, the `_update_countries` method for changing the displayed country list is now executed, which in turn triggers an update of the `view` method." ] }, { @@ -2456,9 +2457,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Parameter-Unterobjekte \n", + "## Parameter sub-objects \n", "\n", - "`Parameterized`-Objekte haben oft Parameterwerte, die selbst `Parameterized`-Objekte sind und eine baumartige Struktur bilden. Mit dem Bedienfeld könnt ihr nicht nur die Parameter des Hauptobjekts bearbeiten, sondern auch auf Unterobjekt durchgreifen. Definieren wir zunächst eine Hierarchie von `Shape`-Klassen deklarieren, die einen Bokeh-Plot des ausgewählten `Shape` zeichnen:" + "`Parameterized` objects often have parameter values that are `Parameterized` objects themselves and form a tree-like structure. With the control panel you can not only edit the parameters of the main object, but also access sub-objects. Let’s first define a hierarchy of `Shape` classes that will draw a bokeh plot of the selected `Shape`:" ] }, { @@ -2515,7 +2516,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Jetzt, da wir mehrere `Shape`-Klassen haben, können wir Instanzen davon erstellen und einen `ShapeViewer` erstellen, um zwischen ihnen auszuwählen. Wir können auch zwei Methoden mit Parameterabhängigkeiten deklarieren, die den Plot und den Plot-Titel aktualisieren. Hierbei ist zu beachten, dass der `param.depends`-Dekorator nicht nur von Parametern am Objekt selbst abhängen kann, sondern auch von bestimmten Parametern am Unterobjekt, z.B. `shape.radius` oder von Parametern des Unterobjekts mit `shape.param` ausgedrückt werden kann." + "Now that we have multiple `Shape` classes we can create instances of them and create a `ShapeViewer` to choose between. We can also declare two methods with parameter dependencies that update the plot and the plot title. It should be noted that the `param.depends` decorator can not only depend on parameters on the object itself, but can also be expressed on certain parameters on the subobject, for example `shape.radius` or with `shape.param` on parameters of the subobject." ] }, { @@ -2546,13 +2547,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Nachdem wir eine Klasse mit Unterobjekten haben, können wir sie wie gewohnt anzeigen. Drei Hauptoptionen steuern, wie das Unterobjekt gerendert wird:\n", + "Now that we have a class with sub-objects, we can display them as usual. Three main options control how the sub-object is rendered:\n", "\n", - "* `expand`: ob das Unterobjekt bei der Initialisierung erweitert wird (`default=False`)\n", - "* `expand_button`: ob eine Schaltfläche zum Umschalten der Erweiterung vorhanden sein soll; ansonsten ist es auf den initialen `expand`-Wert festgelegt (`default=True`)\n", - "* `expand_layout`: Ein Layout-Typ oder eine Instanz zum Erweitern des Plots in (`default=Column`)\n", + "* `expand`: whether the sub-object is expanded during initialisation (`default=False`)\n", + "* `expand_button`: whether there should be a button to toggle the extension; otherwise it is set to the initial `expand` value (`default=True`)\n", + "* `expand_layout`: A layout type or instance to extend the plot in (`default=Column`)\n", "\n", - "Beginnen wir mit der Standardansicht, die eine Umschaltfläche zum Erweitern des Unterobjekts bietet:" + "Let’s start with the standard view, which has a toggle button to expand the sub-object:" ] }, { @@ -2677,7 +2678,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ können wir eine völlig getrennte `expand_layout`-Instanz für einen Param-Bereich bieten, die mit `expand` und `expand_button`-Option immer ausgeklappt bleibt. Dies ermöglicht uns, die Haupt-Widgets und die Widgets des Unterobjekts getrennt anzuordnen:" + "Alternatively, we can offer a completely separate `expand_layout` instance for a param area, which with the `expand` and `expand_button` option always remains expanded. This allows us to separate the main widgets and the sub-object’s widgets:" ] }, { diff --git a/docs/web/dashboards/panel/pipelines.ipynb b/docs/web/dashboards/panel/pipelines.ipynb index 763c69c3..4a5f0bbd 100644 --- a/docs/web/dashboards/panel/pipelines.ipynb +++ b/docs/web/dashboards/panel/pipelines.ipynb @@ -6,7 +6,7 @@ "source": [ "# Pipelines\n", "\n", - "In [Parametrisierung](https://jupyter-tutorial.readthedocs.io/de/latest/jupyter/dashboards/panel/params.html) wurde beschrieben, wie Klassen erstellt werden, die Parameter deklarieren und mit Berechnungen oder Visualisierungen verknüpfen. In diesem Abschnitt erfahrt ihr, wie ihr mehrere solcher Panels mit einer Pipeline verbinden könnt um komplexe Workflows auszudrücken, bei denen die Ausgabe einer Stufe in die nächste Stufe eingespeist wird." + "In [parameterisation](params.ipynb) is described how classes are created, which declare the parameters and link calculations or visualisations. In this section you will learn how you can connect several such panels with a pipeline to express complex workflows in which the output of one stage is fed into the next stage." ] }, { @@ -1434,18 +1434,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Während wir früher bereits gesehen haben, wie Methoden mit dem `param.depends`-Decorator verknüpft werden, verwenden Pipelines einen anderen Decorator und eine Konvention zum Anzeigen der Objekte. Der `param.output`-Decorator bietet eine Möglichkeit, die Methoden einer Klasse mit Anmerkungen zu versehen, indem seine Ausgaben deklariert werden. `Pipeline` verwendet diese Informationen, um zu bestimmen, welche Ausgaben verfügbar sind, um in die nächste Stufe des Workflows eingespeist zu werden. Im folgenden Beispiel hat die Klasse `Stage1` zwei Parameter (`a` und `b`) und eine Ausgabe `c`. Die Signatur des Decorators ermöglicht eine Reihe von verschiedenen Möglichkeiten, die Ausgaben zu deklarieren:\n", + "While we saw earlier how methods are linked to the `param.depends` decorator, pipelines use a different decorator and a convention for displaying the objects. The `param.output` decorator provides a way to annotate the methods of a class by declaring its output. `Pipeline` uses this information to determine what outputs are available to be fed into the next stage of the workflow. In the following example, the class `Stage1` has two parameters (`a` and `b`) and an output `c`. The decorator’s signature allows a number of different ways to declare the outputs:\n", "\n", - "* `param.output()`: Wenn eine Ausgabe ohne Argumente deklariert wird, gibt die Methode eine Ausgabe zurück, die den Namen der Methode erbt und keine spezifischen Typdeklarationen vornimmt.\n", - "* `param.output(param.Number)`: Beim Deklarieren einer Ausgabe mit einem bestimmten Parameter oder einem Python-Typ wird die Ausgabe mit einem bestimmten Typ deklariert.\n", - "* `param.output(c=param.Number)`: Wenn eine Ausgabe mit einem Keyword-Argument deklariert wird, könnt ihr damit den Methodennamen als Namen der Ausgabe überschreiben und den Typ deklarieren.\n", + "* `param.output()`: If output is declared with no arguments, the method returns output that inherits the name of the method and does not make any specific type declarations.\n", + "* `param.output(param.Number)`: When declaring an output with a specific parameter or a Python type, the output is declared with a specific type.\n", + "* `param.output(c=param.Number)`: If an output is declared with a keyword argument, you can overwrite the method name as the name of the output and declare the type.\n", "\n", - "Es ist auch möglich, mehrere Parameter als Keywords oder als Tupel zu deklarieren:\n", + "It is also possible to declare several parameters as keywords or as tuples:\n", "\n", "* `param.output(c=param.Number, d=param.String)`\n", "* `param.output(('c', param.Number), ('d', param.String))`\n", "\n", - "Im folgenden Beispiel ist die Ausgabe einfach das Ergebnis der Multiplikation der beiden Eingaben (`a` und `b`), die die Ausgabe `c` erzeugen. Zusätzlich deklarieren wir eine `view`-Methode, die einen `LaTeX`-Pane zurückgibt. Schließlich gibt eine `panel`-Methode ein Panel-Objekt zurück, das sowohl die Parameter als auch den View rendern." + "In the example below, the output is simply the result of multiplying the two inputs (`a` and `b`) that produce the output `c`. In addition, we declare a `view` method that returns a `LaTeX` pane. Finally, a `panel` method returns a Panel object that render both the parameters and the view." ] }, { @@ -1585,13 +1585,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Zusammenfassend haben wir einige Konventionen befolgt, um diese Phase unserer Pipeline zu erstellen:\n", + "In summary, we followed a few conventions to create this stage of our pipeline:\n", "\n", - "1. Deklarieren einer parametrisierten Klasse mit einigen Eingabeparametern\n", - "2. Deklarieren und Benennen einer oder mehrerer Ausgabemethoden\n", - "3. Deklarieren einer `panel`-Methode, die einen View des Objekts zurückgibt, das von der Pipeline gerendert werden kann.\n", + "1. Declare a parameterised class with some input parameters\n", + "2. Declare and name one or more output methods\n", + "3. Declare a `panel` method that returns a View of the object that the pipeline can render.\n", "\n", - "Nachdem das Objekt nun instanziiert wurde, können wir es auch nach seinen Ausgaben befragen:" + "Now that the object has been instantiated, we can also ask it about its outputs:" ] }, { @@ -1623,7 +1623,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir können sehen, dass `Stage1` eine Ausgabe mit dem Namen `c` und dem Typ `Number` deklariert, auf die mit der `output`-Methode zugegriffen werden kann. Nun fügen wir `stage1` mit `add_stage` unserer Pipeline hinzu:" + "We can see that `Stage1` declared an output with the name `c` of the type `Number` that can be accessed using the `output` method. Now let’s add `stage1` with `add_stage` to our pipeline:" ] }, { @@ -1639,7 +1639,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Für eine Pipeline benötigen wir jedoch noch mindestens eine `stage2`, das das Ergebnis von `stage1` weiterverarbeitet. Daher sollte ein Parameter `c` aus dem Ergebnis von `stage1` deklariert werden. Als weiteren Parameter definieren wir `exp` und erneut eine `view`-Methode, die von den beiden Parametern und der `panel`-Methode abhängt." + "For a pipeline, however, we still need at least one `stage2` that processes the result of `stage1`. Therefore a parameter `c` should be declared from the result of `stage1`. As a further parameter, we define `exp` and a `view` method again, which depends on the two parameters and the `panel` method." ] }, { @@ -1772,7 +1772,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Auch `stage2` fügen wir nun dem `pipeline`-Objekt hinzu:" + "Also, we now add `stage2` to the `pipeline` object:" ] }, { @@ -1788,7 +1788,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir haben nun eine zweistufige Pipeline, bei der der Output `c` von `stage1` an `stage2` übergeben wird. Nun können wir uns die Pipeline anzeigen lassen mit `pipeline.layout`:" + "We now have a two-stage pipeline where the output `c` is passed from `stage1` to `stage2`. Now we can display the pipeline with `pipeline.layout`:" ] }, { @@ -1915,9 +1915,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Rendering der Pipeline zeigt ein kleines Diagramm mit den verfügbaren Workflow-Stufen sowie die Schaltflächen *Previous* und *Next*, um zwischen den einzelnen Phasen wechseln zu können. Dies ermöglicht die Navigation auch in komplexeren Workflows mit sehr viel mehr Phasen.\n", + "The rendering of the pipeline shows a small diagram with the available workflow stages and the *Previous* and *Next* buttons to switch between the individual phases. This enables navigation even in more complex workflows with many more phases.\n", "\n", - "Oben haben wir jede Stufe einzeln instanziiert. Wenn die Pipeline jedoch als Server-App deployed werden soll, können die Stufen jedoch auch als Teil des Konstruktors deklariert werden:" + "Above we instantiated each level individually. However, if the pipeline is to be deployed as a server app, the stages can also be declared as part of the constructor:" ] }, { @@ -2050,7 +2050,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dabei können die Pipeline-Stufen entweder `Parameterized`-Instanzen oder `Parameterized`-Klassen sein. Bei Instanzen müsst ihr jedoch darauf achten, dass die Aktualisierung der Parameter der Klasse auch den aktuellen Status der Klasse aktualisiert." + "The pipeline stages can either be `Parameterized` instances or `Parameterized` classes. With instances, however, you have to make sure that the update of the parameters of the class also updates the current status of the class." ] } ], diff --git a/docs/web/dashboards/panel/style.ipynb b/docs/web/dashboards/panel/style.ipynb index 9caeb522..a977e423 100644 --- a/docs/web/dashboards/panel/style.ipynb +++ b/docs/web/dashboards/panel/style.ipynb @@ -7,7 +7,7 @@ "\n", "# Styling\n", "\n", - "Panel-Objekte bauen auf [param](https://param.pyviz.org/) auf, wodurch für sie Parameter angegeben werden können, die Benutzer flexibel bearbeiten können, um die angezeigte Ausgabe zu steuern. Zusätzlich zu den für jede Komponente und Komponentenklasse spezifischen Parametern definieren alle Komponenten einen gemeinsamen Satz von Parametern, um die Größe und den Stil des gerenderten View zu steuern." + "Panel objects build on [param](https://param.pyviz.org/), which allows them to be specified by parameters so that users can flexibly edit to control the output displayed. In addition to the parameters specific to each component and component class, all components define a common set of parameters to control the size and style of the rendered view." ] }, { @@ -1364,7 +1364,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Styling-Komponenten \n" + "## Styling components" ] }, { @@ -1373,9 +1373,9 @@ "source": [ "### `css_classes`\n", "\n", - "Der`css_classes`-Parameter ermöglicht die Zuordnung einer Panel-Komponente zu einer oder mehreren CSS-Klassen. CSS-kann direkt im Notebook angegeben werden oder als Verweis auf eine externe CSS-Datei, indem sie mit `raw_css` oder `css_files` als Liste an die *Panel extension* übergeben werden. Außerhalb eines Notebooks, in einem externen Modul oder einer Bibliothek, können wir mit `pn.config.raw_css` und `pn.config.js_files` Konfigurationsparameter anhängen.\n", + "The `css_classes` parameter enables a panel component to be assigned to one or more CSS classes. CSS can be specified directly in the notebook or as a reference to an external CSS file by passing it to the Panel extension with `raw_css` or `css_files` as a list. Outside a notebook, in an external module or library, we can attach configuration parameters with `pn.config.raw_css` and `pn.config.js_files`.\n", "\n", - "Um diese Verwendung zu demonstrieren, definieren wir eine CSS-Klasse mit dem Namen, `widget-box`:" + "To demonstrate this usage, let’s define a CSS class named `widget-box`:" ] }, { @@ -2858,7 +2858,7 @@ "source": [ "### `background`\n", "\n", - "Wenn wir der Komponente einfach einen Hintergrund geben möchten, können wir einen als Hex-String definieren:" + "If we just want to give the component a background, we can define one as a hex string:" ] }, { @@ -2975,7 +2975,7 @@ "source": [ "### `style`\n", "\n", - "Bestimmte Komponenten, insbesondere markupbezogene Panes, stellen einen `style`-Parameter zur Verfügung, mit dem CSS-Stile definiert werden können, die auf den HTML-Container des Fensterinhalts angewendet werden, z.B. das `Markdown`-Pane:" + "Certain components, especially markup-related panes, provide a `style` parameter that can be used to define CSS styles that are applied to the HTML container of the window content, e.g. the `Markdown` pane:" ] }, { @@ -3090,9 +3090,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Komponentengröße und Layout\n", + "## Component size and layout\n", "\n", - "Die Größe der Komponenten und ihr Abstand werden auch über eine Reihe von Parametern gesteuert, die von allen Komponenten gemeinsam verwendet werden." + "The size of the components and their spacing are also controlled by a number of parameters that are shared by all components." ] }, { @@ -3101,7 +3101,7 @@ "source": [ "### `margin`\n", "\n", - "Der `margin`-Parameter kann verwendet werden, um Platz rund um ein Element zu schaffen, das als Anzahl der Pixel in der Reihenfolge oben, rechts, unten und links definiert ist, z.B.:" + "The `margin` parameter can be used to create space around an element, which is defined as the number of pixels in the order top, right, bottom and left, e.g." ] }, { @@ -3225,9 +3225,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Absolute Dimensionierung mit `width` und `height`\n", + "### Absolute dimensioning with `width` and `height`\n", "\n", - "Standardmäßig verwenden alle Komponenten entweder die automatische oder die absolute Größenänderung. Bedienfelder nehmen im Allgemeinen so viel Platz ein wie die darin enthaltenen Komponenten, und text- oder bildbasierte Bedienfelder passen sich an die Größe ihres Inhalts an. Um eine feste Größe für eine Komponente festzulegen, ist es normalerweise ausreichend, eine Breite oder Höhe festzulegen. In bestimmten Fällen muss jedoch `sizing_mode='fixed'` explizit angegeben werden." + "By default, all components use either automatic or absolute resizing. Panels generally take up as much space as the components they contain, and text- or image-based panels adjust to the size of their content. To set a fixed size for a component, it is usually sufficient to set a width or height. In certain cases, however, `sizing_mode='fixed'` must be specified explicitly." ] }, { @@ -3350,15 +3350,15 @@ "source": [ "### `sizing_mode` \n", "\n", - "`sizing_mode` kann die folgenden Werte annehmen:\n", + "`sizing_mode` can have the following values:\n", "\n", - "* `fixed`: Die Komponente ist nicht responsive. Die ursprüngliche Breite und Höhe wird unabhängig von nachfolgenden Ereignissen zur Größenänderung des Browserfensters beibehalten. Dies ist das Standardverhalten und verwendet einfach die angegebene Breite und Höhe.\n", - "* `stretch_width`: Die Komponente passt die Größe an, um sie auf die verfügbare Breite zu strecken, ohne jedoch das Seitenverhältnis beizubehalten. Die Höhe der Komponente hängt vom Typ der Komponente ab und kann fest oder an den Inhalt der Komponente gebunden sein.\n", - "* `stretch_height`: Die Größe der Komponente wird ansprechend angepasst, um sie auf die verfügbare Höhe zu erreichen, ohne jedoch das Seitenverhältnis beizubehalten. Die Breite der Komponente hängt vom Typ der Komponente ab und kann fest oder an den Inhalt der Komponente gebunden sein. \n", - "* `stretch_both`: Die Komponente ist responsive, unabhängig von Breite und Höhe, und belegt den gesamten verfügbaren horizontalen und vertikalen Raum, auch wenn sich dadurch das Seitenverhältnis der Komponente ändert.\n", - "* `scale_height`: Die Größe der Komponente wird ansprechend angepasst, um sie auf die verfügbare Höhe zu strecken, wobei das ursprüngliche oder bereitgestellte Seitenverhältnis beibehalten wird.\n", - "* `scale_width`: Die Größe der Komponente wird ansprechend angepasst, um sie auf die verfügbare Breite zu strecken, wobei das ursprüngliche oder bereitgestellte Seitenverhältnis beibehalten wird.\n", - "* `scale_both`: Die Größe der Komponente wird ansprechend auf die verfügbare Breite und Höhe angepasst, wobei das ursprüngliche oder bereitgestellte Seitenverhältnis beibehalten wird." + "* `fixed`: The component is not responsive. The original width and height are retained regardless of subsequent events that resize the browser window. This is the default behavior and just uses the specified width and height.\n", + "* `stretch_width`: The component resizes to stretch it to the available width without maintaining the aspect ratio. The height of the component depends on the type of component and can be fixed or tied to the content of the component.\n", + "* `stretch_height`: The component is resized appropriately to fit the available height, but without maintaining the aspect ratio. The width of the component depends on the type of component and can be fixed or tied to the content of the component. \n", + "* `stretch_both`: The component is responsive, regardless of width or height, and occupies all available horizontal and vertical space, even if this changes the aspect ratio of the component.\n", + "* `scale_height`: The component is resized appropriately to stretch it to the available height while maintaining the original or provided aspect ratio.\n", + "* `scale_width`: The component is resized appropriately to stretch it to the available width while maintaining the original or provided aspect ratio.\n", + "* `scale_both`: The component is resized to the available width and height, while maintaining the original or provided aspect ratio." ] }, { @@ -3802,7 +3802,7 @@ "source": [ "### `Spacer`\n", "\n", - "`Spacer` sind eine sehr vielseitige Komponente, mit der sich feste oder responsive Abstände zwischen Objekten problemlos herstellen lassen. Wie alle anderen Komponenten unterstützen `Spacer` sowohl den absoluten als auch den responsiven Modus:" + "`Spacer` are a very versatile component that can be used to easily create fixed or responsive distances between objects. Like all other components `Spacer` support both absolute and responsive mode:" ] }, { @@ -3926,7 +3926,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`VSpacer` und `HSpacer` sorgen für einen ansprechenden vertikalen bzw. horizontalen Abstand. Mit diesen Komponenten können wir Objekte in einem Layout in gleichem Abstand platzieren und den leeren Bereich verkleinern, wenn die Größe des Browsers geändert wird:" + "`VSpacer` and `HSpacer` ensure an attractive vertical or horizontal distance. With these components we can place objects equidistantly on a layout and shrink the empty area when the browser is resized:" ] }, { diff --git a/docs/web/dashboards/panel/templates.ipynb b/docs/web/dashboards/panel/templates.ipynb index 4ad411fb..c4d50ffe 100644 --- a/docs/web/dashboards/panel/templates.ipynb +++ b/docs/web/dashboards/panel/templates.ipynb @@ -6,9 +6,9 @@ "source": [ "# Templates\n", "\n", - "Wenn ihr eine Panel-App oder ein Dashboard als Bokeh-Anwendung bereitstellen wollt, wird diese in einem Standard-Template gerendert, das auf die JS- und CSS-Ressourcen sowie das eigentliche Panel-Objekt verweist. Wenn ihr das Layout der bereitgestellten App anpassen wollt oder mehrere separate Panels in eine App bereitstellen wollt, ermöglicht euch die `Template`-Komponente von Panel das Anpassen dieses Standard-Templates.\n", + "If you want to provide a panel app or a dashboard as a bokeh application, it is rendered in a standard template that refers to the JS and CSS resources as well as the actual panel object. If you want to adapt the layout of the provided app or if you want to provide several separate panels in one app, the `Template` component of Panel allows you to adapt this standard template.\n", "\n", - "Ein solches Template wird mithilfe von [Jinja2](http://jinja.pocoo.org/docs/) definiert, wobei ihr das Standard-Template erweitert oder sogar vollständig ersetzen könnt. Im Folgenden seht ihr ein Beispiel:\n", + "Such a template is defined with [Jinja2](http://jinja.pocoo.org/docs/), whereby you can extend or even completely replace the standard template. Here is an example:\n", "\n", " \n", " \n", @@ -52,14 +52,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Template definiert eine Reihe von benutzerdefinierten Blöcken, die durch `extends` ergänzt oder überschrieben werden können:" + "The template defines a number of user-defined blocks that can be supplemented or overwritten by `extends`:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Benutzerdefinierte Templates verwenden" + "## Use custom templates" ] }, { @@ -1417,9 +1417,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Sobald wir Panel geladen haben, können wir mit der Definition eines benutzerdefinierten Templates beginnen. Normalerweise ist es am einfachsten, ein vorhandenes Template durch Überschreiben bestimmter Blöcke anzupassen. Mit `{% extends base %}` erklären wir, dass wir lediglich eine vorhandene Vorlage erweitern und keine neue definieren.\n", + "Once we have Panel loaded, we can start defining a custom template. It is usually easy to customise an existing template by overwriting certain blocks. With `{% extends base %}` we declare that we are only expanding an existing template and not defining a new one.\n", "\n", - "Im folgenden Fall erweitern wir den `postamble`-Block des Headers, um eine zusätzliche Ressource zu laden, und den `contents`-Block, um die Anordnung der Komponenten neu zu definieren:" + "In the following case, we are expanding the `postamble` block of the header to load an additional resource and the `contents` block to redefine the arrangement of the components:" ] }, { @@ -1459,7 +1459,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Mithilfe des `embed`-Makros haben wir zwei verschiedene `roots` in der Vorlage definiert. Um die Vorlage rendern zu können, müssen wir nun zuerst das `pn.Template`-Objekt mit dem HTML-Template erstellen und dann die beiden `roots`-Objekte einbinden." + "Using the `embed` macro, we have defined two different `roots` in the template. In order to be able to render the template, we must first create the `pn.Template` object with the HTML template and then integrate the two `roots` objects." ] }, { @@ -1581,14 +1581,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Im Notebook ewird ein Button gerendert, mit dem ihr einen lokalen Server starten könnt um zu überprüfen, ob die Ausgabe Ihren Erwartungen entspricht." + "A button is rendered in the notebook with which you can start a local server to check whether the output meets your expectations." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn das Template größer ist, ist es oft einfacher, es in einer separaten Datei zu erstellen. Ihr könnt den Lademechanismus für Jinja2-Vorlagen verwenden, indem ihr ein Environment zusammen mit einem `loader` definiert:" + "If the template is larger, it is often easier to create it in a separate file. You can use the Jinja2 template loading mechanism by defining an environment together with a `loader`:" ] }, { diff --git a/docs/web/dashboards/panel/widgets.ipynb b/docs/web/dashboards/panel/widgets.ipynb index 42862876..30515547 100644 --- a/docs/web/dashboards/panel/widgets.ipynb +++ b/docs/web/dashboards/panel/widgets.ipynb @@ -6,9 +6,9 @@ "source": [ "# Widgets\n", "\n", - "`Panel` bietet eine breite Palette von Widgets zur präzisen Steuerung von Parameterwerten. Die Widget-Klassen verwenden eine konsistente API, mit der breite Kategorien von Widgets als austauschbar behandelt werden können. Um beispielsweise einen Wert aus einer Liste von Optionen auszuwählen, können Sie ein `SelectWidget`, ein `RadioButtonGroup`-Widget oder ein gleichwertiges Widget austauschbar verwenden.\n", + "`Panel` offers a wide range of widgets for precise control of parameter values. The widget classes use a consistent API that allows broad categories of widgets to be treated as interchangeable. For example, to select a value from a list of options, you can use `SelectWidget`, a `RadioButtonGroup`widget, or an equivalent widget interchangeably.\n", "\n", - "Wie alle anderen Komponenten in `Panel`, können auch `Widget`-Objekte ihren Zustand sowohl im Notebook als auch auf dem Bokeh-Server synchronisieren:" + "Like all other components in `Panel`, `Widget` objects can also synchronise their state both in the notebook and on the bokeh server:" ] }, { @@ -1473,7 +1473,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr den Textwert ändert, wird der entsprechende Parameter automatisch aktualisiert:" + "If you change the text value, the corresponding parameter is automatically updated:" ] }, { @@ -1500,7 +1500,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Durch Aktualisieren des Parameterwerts wird auch das Widget aktualisiert:" + "Updating the parameter value also updates the widget:" ] }, { @@ -1516,9 +1516,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Callbacks und Links\n", + "## Callbacks and links\n", "\n", - "Um eine Parameteränderung mitzubekommen, können wir `widget.param.watch` mit dem zu beobachtenden Parameter un einer Funktion aufrufen:" + "In order to notice a parameter change, we can call a function `widget.param.watch` with the parameter to be observed:" ] }, { @@ -1547,7 +1547,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn wir `widget.value` nun ändern, wird das resultierende *Event* ausgegeben." + "If we change now `widget.value`, the resulting event is output." ] }, { @@ -1571,7 +1571,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "PanelWidgets ermöglichen in Kombination mit Objekten die einfache Erstellung interaktiver Dashboards und Visualisierungen. Weitere Informationen zum Definieren von Rückrufen und Verknüpfungen zwischen Widgets und anderen Komponenten findet ihr im Benutzerhandbuch zu Verknüpfungen ." + "PanelWidgets, in combination with objects, enable the easy creation of interactive dashboards and visualisations. For more information on defining callbacks and links between widgets and other components, see the User Guide." ] }, { @@ -1580,7 +1580,7 @@ "source": [ "## Widgets\n", "\n", - "Um mehrere Widgets zusammenzustellen, können sie zu einem`Row`-, `Column`- oder `Tabs`-Panel hinzugefügt werden. Weitere Informationen zum Layout von Widgets und Bedienfeldern findet ihr im [customization user guide](https://panel.pyviz.org/user_guide/Customization.html)." + "To put several widgets together, they can be added to a `Row`-, `Column`- or `Tabs` panel. For more information on the layout of widgets and control panels, see the [customization user guide](https://panel.pyviz.org/user_guide/Customization.html)." ] }, { @@ -1698,62 +1698,63 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Widget-Kategorien\n", + "## Widget categories\n", "\n", - "Die unterstützten Widgets können anhand ihrer kompatiblen APIs in verschiedene Kategorien eingeteilt werden.\n", + "The supported widgets can be divided into different categories based on their compatible APIs.\n", "\n", - "### Optionsauswahl\n", + "### Option selection\n", "\n", - "Mit Optionsauswahl-Widgets könnt ihr einen oder mehrere Werte aus einer `list` oder einem `dictionary` auswählen. Alle Widgets dieses Typs haben `options` und `value`-Parameter.\n", + "With option selection widgets you can select one or more values from a `list` or a `dictionary`. All widgets of this type have `options` and `value` parameters.\n", "\n", - "| Optionen | Widget | Beschreibung |\n", - "|:---------|:-------|:-----------------|\n", - "| **Einzelwerte** | | Mit diesen Widgets könnt ihr einen Wert aus einer `list` oder einem `dictionary` auswählen |\n", - "| | `AutocompleteInput` | wählt einen `value` aus einem sich automatisch vervollständigenden Textfeld |\n", - "| | `DiscretePlayer` | zeigt Steuerelemente des `mediaplayer` an, mit denen ihr die verfügbaren Optionen abspielen und durchgehen könnt |\n", - "| | `DiscreteSlider` | wählt einen Wert mit einem Schieberegler |\n", - "| | `RadioButtonGroup` | wählt einen Wert aus einer Reihe sich gegenseitig ausschließender Umschalttasten |\n", - "| | `RadioBoxGroup` | wählt einen Wert aus einer Reihe sich gegenseitig ausschließender Kontrollkästchen aus |\n", - "| | `Select` | wählt einen Wert aus einem Dropdown-Menü |\n", - "| **Mehrere Werte** | | Mit diesen Widgets könnt ihr mehrere Werte aus einer `list` oder einem `dictionary` auswählen |\n", - "| | `CheckBoxGroup` | wählt Werte aus, indem ihr die entsprechenden Kontrollkästchen aktiviert |\n", - "| | `CheckButtonGroup` | wählt Werte aus, indem ihr die entsprechenden Schaltflächen umschaltet |\n", - "| | `CrossSelector` | wählt Werte aus, indem ihr Elemente zwischen zwei Listen verschiebt |\n", - "| | `MultiSelect` | wählt Werte aus, indem ihr sie in einer Liste markiert |\n", + "| Options | Widget | Description |\n", + "|:--------|:-------|:----------------|\n", + "| **Individual values** | | With these widgets you can choose a value from a `list` or a `dictionary` |\n", + "| | `AutocompleteInput` | selects one `value` rom an automatically completed text field |\n", + "| | `DiscretePlayer` | displays controls of `mediaplayer`, that allow you to play and step through the options available |\n", + "| | `DiscreteSlider` | selects a value with a slider |\n", + "| | `RadioButtonGroup` | selects a value from a series of mutually exclusive toggle keys |\n", + "| | `RadioBoxGroup` | selects a value from a series of mutually exclusive check boxes |\n", + "| | `Select` | selects a value from a drop-down menu |\n", + "| **Multiple values** | | With these widgets you can select several values from a `list` or a `dictionary` |\n", + "| | `CheckBoxGroup` | select values by activating the corresponding check boxes |\n", + "| | `CheckButtonGroup` | select values by toggling the corresponding buttons |\n", + "| | `CrossSelector` | select values by moving items between two lists |\n", + "| | `MultiSelect` | select values by marking them in a list |\n", "\n", - "### Typbasierte Selektoren \n", + "### Type-based selectors \n", "\n", - "Typbasierte Selektoren bieten die Möglichkeit, einen Wert entsprechend seinem Typ auszuwählen. Alle Selektoren verfügen über `value`. Die Widgets in dieser Kategorie können über den Typ hinaus auch andere Validierungsformen aufweisen, z.B. die obere und untere Grenze von Schiebereglern.\n", "\n", - "| | Typen | Widget | Beschreibung |\n", - "|--|:------|:-------|:-----------------|\n", - "| **Einzelwerte** | | | erlaubt die Auswahl eines einzelnen `value`-Typs |\n", - "| | **Numerisch** | | Numerische Selektoren sind durch `start` und `end`-Werte begrenzt |\n", - "| | | `IntSlider` | wählt mit einem Schieberegler einen ganzzahligen Wert innerhalb eines festgelegten Bereichs aus |\n", - "| | | `FloatSlider` | wählt mit einem Schieberegler einen Gleitkommawert innerhalb eines festgelegten Bereichs aus |\n", - "| | | `Player` | zeigt Steuerelemente des `mediaplayer` an, mit denen ihr eine Reihe von Ganzzahlwerten abspielen und durchlaufen könnt |\n", - "| | **Boolesche Werte** | | |\n", - "| | | `Checkbox` | Schaltet eine einzelne Bedingung zwischen `True`/`False` um, indem ein Kontrollkästchen aktiviert wird |\n", - "| | | `Toggle` | Umschalten einer einzelnen Bedingung zwischen `True`/`False`-Zuständen durch Klicken auf eine Schaltfläche |\n", - "| | **Termine** | | |\n", - "| | | `DatetimeInput` | wählt mit einem Textfeld und dem Dienstprogramm zur Datumsauswahl des Browsers einen Datumswert aus |\n", - "| | | `DatePicker` | gebt einen Datums-/Uhrzeitwert als Text ein und analysiert ihn mit einem vordefinierten Formatierer |\n", - "| | | `DateSlider` | wählt mit einem Schieberegler einen Datumswert innerhalb eines festgelegten Bereichs aus. |\n", + "Type-based selectors offer the possibility of choosing a value according to its type. All selectors have a `value`. In addition to the type, the widgets in this category can also have other forms of validation, for example the upper and lower limits of sliders.\n", + "\n", + "| | Types | Widget | Description |\n", + "|--|:------|:-------|:----------------|\n", + "| **Individual values** | | | allows the selection of a single `value` type |\n", + "| | **Numerically** | | Numeric selectors are limited by `start` and `end` values |\n", + "| | | `IntSlider` | selects an integer value within a specified range with a slider |\n", + "| | | `FloatSlider` | uses a slider to select a floating point value within a specified range |\n", + "| | | `Player` | displays controls of the `mediaplayer`, that allow you to play and cycle through a range of integer values |\n", + "| | **Boolean values** | | |\n", + "| | | `Checkbox` | toggles a single condition between `True`/`False` by checking a box |\n", + "| | | `Toggle` | toggles a single condition between `True`/`False` by clicking a button |\n", + "| | **Date** | | |\n", + "| | | `DatetimeInput` | selects a date value using a text box and the browser’s date picker utility |\n", + "| | | `DatePicker` | enters a date/time value as text and analyse it with a predefined formatter |\n", + "| | | `DateSlider` | selects a date value within a specified range with a slider |\n", "| | **Text** | | |\n", - "| | | `TextInput` | gebt eine beliebige Zeichenfolge über ein Texteingabefeld ein |\n", - "| | **Andere** | | |\n", - "| | | `ColorPicker` | wählt eine Farbe mit den Farbauswahl-Dienstprogrammen des Browsers aus. |\n", - "| | | `FileInput` | Ladet eine Datei vom Frontend hoch und macht die Daten und den MIME-Typ in Python verfügbar |\n", - "| | | `LiteralInput` | gebt ein beliebiges Python-Literal über ein Texteingabefeld ein, das dann in Python analysiert wird |\n", - "| **Bereiche** | | | ermöglicht die Auswahl eines Wertebereichs des entsprechenden Typs, der als `(lower, upper)`-Tupel für den `value`-Parameter gespeichert ist |\n", - "| | **Numerisch** | | |\n", - "| | | `IntRangeSlider` | wählt mit einem Schieberegler mit zwei Ziehpunkten einen ganzzahligen Bereich aus |\n", - "| | | `RangeSlider` | wählt mit einem Schieberegler mit zwei Ziehpunkten einen Gleitkommabereich aus |\n", - "| | **Termine** | | |\n", - "| | | `DateRangeSlider` | wählt mit einem Schieberegler mit zwei Ziehpunkten einen Datumsbereich aus |\n", - "| **Andere** | | | |\n", - "| | | `Audio` | zeigt einen Audio-Player an, dem eine Audiodatei lokal oder Remote zugewiesen wurde, und ermöglicht den Zugriff und die Steuerung des Player-Status |\n", - "| | | `Button` | ermöglicht das Auslösen von Ereignissen, wenn auf die Schaltfläche geklickt wird; im Gegensatz zu anderen Widgets hat es keinen `value`-Parameter |" + "| | | `TextInput` | enters any character string via a text entry field |\n", + "| | **Other** | | |\n", + "| | | `ColorPicker` | selects a color using the browser’s color-picking utilities |\n", + "| | | `FileInput` | uploads a file from the frontend and make the data and MIME type available in Python |\n", + "| | | `LiteralInput` | enters any Python literal via a text entry field, which will then be parsed in Python |\n", + "| **Areas** | | | enables the selection of a value range of the corresponding type, which is saved as a `(lower, upper)` tuple for the `value` parameter |\n", + "| | **Numerically** | | |\n", + "| | | `IntRangeSlider` | selects an integer range with a slider with two handles |\n", + "| | | `RangeSlider` | selects a floating point area using a slider with two handles |\n", + "| | **Dates** | | |\n", + "| | | `DateRangeSlider` | selects a date range using a slider with two handles |\n", + "| **Other** | | | |\n", + "| | | `Audio` | displays an audio player to which an audio file has been assigned locally or remotely, and allows access and control of the player status |\n", + "| | | `Button` | allows events to be triggered when the button is clicked; unlike other widgets, it does not have an `value` parameter |" ] } ], diff --git a/docs/web/dashboards/voila/bqplot_vuetify_example.ipynb b/docs/web/dashboards/voila/bqplot_vuetify_example.ipynb index 64aa19f7..fccafd13 100644 --- a/docs/web/dashboards/voila/bqplot_vuetify_example.ipynb +++ b/docs/web/dashboards/voila/bqplot_vuetify_example.ipynb @@ -27,7 +27,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Erster Histogrammplot" + "## First histogram plot" ] }, { @@ -110,7 +110,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Liniendiagramm" + "## Line chart" ] }, { @@ -149,7 +149,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## `BrushIntervalSelector` hinzufügen" + "## Add `BrushIntervalSelector`" ] }, { @@ -173,7 +173,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Zweiter Histogrammplot" + "## Second histogram plot" ] }, { @@ -238,9 +238,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Voila vuetify-Layout einrichten\n", + "## Set up voilà vuetify layout\n", "\n", - "Das Voila vuetify-Template zeigt nicht die Ausgabe des Jupyter Notebook an, sondern nur das Widget mit den `mount_id`-Metadaten." + "The Voila vuetify template does not show the output of the Jupyter Notebook, only the widget with the `mount_id` metadata." ] }, { diff --git a/docs/web/dashboards/voila/index.rst b/docs/web/dashboards/voila/index.rst index 48111fed..eb8b903a 100644 --- a/docs/web/dashboards/voila/index.rst +++ b/docs/web/dashboards/voila/index.rst @@ -1,35 +1,31 @@ Voilà ===== -`Voilà `_ wurde von `QuantStack -`_ entwickelt. +`Voilà `_ was developed by +`QuantStack `_. Features -------- -* Voilà unterstützt :doc:`interaktive Jupyter-Widgets - `, einschließlich der Roundtrips zum - Kernel. Auch benutzerdefinierte Widgets wie - :doc:`pyviz:d3js/bqplot/index`, +* Voilà supports :doc:`interactive Jupyter widgets + `, including round trips to the kernel. + Custom widgets like :doc:`pyviz:d3js/bqplot/index`, :doc:`pyviz:js/ipyleaflet`, :doc:`pyviz:js/ipyvolume`, `ipympl `_, :doc:`ipysheet `, `plotly `_, - `ipywebrtc `_ usw. werden - unterstützt. -* Voilà erlaubt keine willkürliche Ausführung von Code durch Nutzer von - Dashboards. -* Voilà basiert auf Jupyter-Standardprotokollen und -Dateiformaten und - funktioniert mit jedem - :doc:`Jupyter-Kernel `: C++, Python, Julia. - Dies macht es zu einem sprachunabhängigen Dashboard-System. -* Voilà ist erweiterbar. Es enthält ein flexibles :doc:`Template - `-System zur Erstellung - umfangreicher Layouts. + `ipywebrtc `_ etc. are also + supported. +* Voilà does not allow arbitrary code execution by dashboard users. +* Voilà is based on Jupyter standard protocols and file formats and works with + any :doc:`Jupyter-Kernel `: C++, Python, + Julia. This makes it a language-independent dashboard system. +* Voilà is expandable. It contains a flexible :doc:`Template ` + system for creating extensive layouts. -Ausführungsmodell ------------------ +Execution model +--------------- .. graphviz:: @@ -41,19 +37,19 @@ Ausführungsmodell subgraph cluster_browser { notebook_url [ shape=box, - label="Notebook URL"; + label="Notebook url"; style=filled; fillcolor="#edf8fb"; color="#b2e2e2"]; html_rendering [ shape=box, - label="HTML-Rendering"; + label="HTML rendering"; style=filled; fillcolor="#edf8fb"; color="#b2e2e2"]; init_websocket [ shape=box, - label="Javascript initiiert Websocket\nmit dem Jupyter-Kernel", + label="Javascript initiates Websocket\nwith the Jupyter kernel", style=filled; fillcolor="#edf8fb"; color="#b2e2e2"]; @@ -63,19 +59,19 @@ Ausführungsmodell subgraph cluster_server { html_open_notebook [ shape=box, - label="Notebook öffnen und\nzugehörigen Kernel starten"; + label="Open the notebook and start\nthe associated kernel"; style=filled; fillcolor="#bdd7e7"; color="#2171b5"]; html_run_notebook [ shape=box, - label="Notebook-Zellen ausführen\nErgebnisse ausgeben\nVoilà-Template zuweisen\nNotebook konvertieren"; + label="Run notebook cells\nOutput results\nAssign Voilà template\nConvert notebook"; style=filled; fillcolor="#bdd7e7"; color="#2171b5"]; ws_open_notebook [ shape=box, - label="Notebook öffnen und\nzugehörigen Kernel starten"; + label="Open the notebook and\nstart the associated kernel"; style=filled; fillcolor="#bdd7e7"; color="#2171b5"]; @@ -85,7 +81,7 @@ Ausführungsmodell // Edges notebook_url -> html_open_notebook [label="GET Request"] html_open_notebook -> html_run_notebook - html_run_notebook -> html_rendering [label="HTTP Responses\lmit HTML oder\lHTML-Fragmenten\l"] + html_run_notebook -> html_rendering [label="HTTP Responses\lwith HTML or\lHTML fragments\l"] html_rendering -> init_websocket init_websocket -> ws_open_notebook [dir=both label="Web-Socket:\l- comm_msg\l- comm_info_request\l- kernel_info_request\l- shutdown_request\l"] // Arrangement @@ -93,17 +89,17 @@ Ausführungsmodell {rank = same; html_open_notebook; html_run_notebook; ws_open_notebook;} } -Ein wichtiger Aspekt dieses Ausführungsmodells ist, dass vom Frontend nicht -angegeben werden kann, welcher Code vom Backend ausgeführt wird. Sofern mit der -Option ``--strip-sources=False`` nicht anders angegeben, gelangt der Quellcode -des gerenderten Notizbuchs noch nicht einmal an das Frontend. Die Voilà-Instanz -des ``jupyter_server`` erlaubt standardmäßig keine Ausführungsanforderungen. +An important aspect of this execution model is that the frontend cannot specify +which code is executed by the backend. Unless otherwise specified with the option +``--strip-sources=False``, the source code of the rendered notebook does not +even reach the frontend. The Voilà instance of ``jupyter_server`` does not allow +execution requests by default. .. warning:: - Die aktuelle Version von Voilà antwortet auf den ersten ``GET``-Request - erst, wenn alle Zellen ausgeführt wurden. Dies kann länger dauern. Es wird - jedoch daran gearbeitet, progressives Rendern zu ermöglichen, s. `feat: - progressive cell rendering + The current version of Voilà does not respond to the first ``GET`` request + until all cells have been executed. This can take longer. However, work is + being done to enable progressive rendering, s. `feat: progressive cell + rendering `_. .. seealso:: diff --git a/docs/web/dashboards/voila/install.rst b/docs/web/dashboards/voila/install.rst index daf8a445..9c512d6f 100644 --- a/docs/web/dashboards/voila/install.rst +++ b/docs/web/dashboards/voila/install.rst @@ -1,10 +1,10 @@ -Installation und Nutzung -======================== +Installation and use +==================== Installation ------------ -voilà kann installiert werden mit: +voilà can be installed with: .. code-block:: console @@ -15,29 +15,29 @@ voilà kann installiert werden mit: Successfully installed jupyter-server-0.1.1 jupyterlab-pygments-0.1.0 voila-0.1.10 … -Starten -------- +Start +----- -… als eigenständige Anwendung -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +… as a stand-alone application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Ihr könnt die Installation überprüfen,z.B. mit: +You can check the installation, e.g. with: .. code-block:: console - $ pipenv run voila docs/workspace/jupyter/ipywidgets/examples.ipynb + $ pipenv run voila pipenv run voila docs/workspace/jupyter/ipywidgets/examples.ipynb … [Voila] Voila is running at: http://localhost:8866/ -Hierbei sollte sich euer Standardbrowser öffnen und die ``ipywidget``-Beispiele -aus unserem Tutorial anzeigen: +Your standard browser should open and display the ``ipywidget`` examples from +our tutorial: .. image:: voila-example-1.png - :alt: Voilà-Beispiel examples.ipynb + :alt: Voilà example examples.ipynb -Alternativ könnt ihr euch auch ein Verzeichnis anzeigen lassen mit allen darin -enthaltenen Notebooks: +Alternatively, you can also display a directory with all the notebooks it +contains: .. code-block:: console @@ -45,9 +45,9 @@ enthaltenen Notebooks: … .. image:: voila-example-2.png - :alt: Voilà-Beispiel für eine Verzeichnisansicht + :alt: Voilà example of a directory view -Es ist auch möglich, sich den Quellcode anzeigen zu lassen mit: +It is also possible to display the source code with: .. code-block:: console @@ -55,29 +55,29 @@ Es ist auch möglich, sich den Quellcode anzeigen zu lassen mit: … .. note:: - Beachtet, dass der Code nur angezeigt wird. Voilà erlaubt Benutzern nicht, - den Code zu bearbeiten oder auszuführen. + Note that the code is only displayed. Voilà does not allow users to edit or + run the code. .. image:: voila-example-3.png - :alt: Voilà-Beispiel mit Quellcode + :alt: Voilà example with source code -Üblicherweise wird das ``light``-Theme verwendet; ihr könnt jedoch auch das -``dark``-Theme auswählen: +Usually the ``light`` theme is used; however, you can also choose the ``dark`` +theme: .. code-block:: console $ pipenv run voila --theme=dark docs/workspace/jupyter/ipywidgets/examples.ipynb … -… als Erweiterung des Jupyter-Server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +… as an extension of the Jupyter server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Alternativ könnt ihr voilà auch als Erweiterung des Jupyter-Server starten: +Alternatively you can start voilà as an extension of the Jupyter server: .. code-block:: console $ pipenv run jupyter notebook … -Anschließend könnt ihr voilà aufrufen, z.B. unter der URL +Then you can call up voilà, e.g. under the URL ``http://localhost:8888/voila``. diff --git a/docs/web/dashboards/voila/templating.rst b/docs/web/dashboards/voila/templating.rst index 0c5024e9..5bd569e5 100644 --- a/docs/web/dashboards/voila/templating.rst +++ b/docs/web/dashboards/voila/templating.rst @@ -3,29 +3,27 @@ Templating .. _voila-gridstack: -Voila-Gridstack +Voilà gridstack --------------- -`gridstack.js `_ ist ein jQuery-Plugin für -Widget-Layouts. Dies ermöglicht mehrspaltige Drag & Drop-Raster und anpassbare, -für `Bootstrap v3 `_ geeignete Layouts. -Zudem funktioniert es mit `knockout.js `_ und -Touch-Geräten. +`gridstack.js `_ is a jQuery plugin for widget layouts. +This enables multi-column drag and drop grids and customizable layouts suitable +for `Bootstrap v3 `_. It also works with +`knockout.js `_ and touch devices. -Das Gridstack-Voilà-Template verwendet die Metadaten der Notebook-Zellen, um das -Layout des Notebooks zu gestalten. Es soll die gesamte Spezifikation für die -veralteten :doc:`../jupyter-dashboards/index` -unterstützen. +The Gridstack Voilà template uses the metadata of the notebook cells to design +the notebook’s layout. It is supposed to support the entire specification for +the outdated :doc:`../jupyter-dashboards/index`. .. image:: voila-gridstack.png :scale: 53% - :alt: Beispiel für Voilà-Gridstack + :alt: Example for Voilà gridstack voila-vuetify ------------- -`voila-vuetify `_ ist ein Template -zur Verwendung von Voilà mit dem `Material Design Component Framework +`voila-vuetify `_ is a template for +using Voilà with the `Material Design Component Framework `_ `Vuetify.js `_. Installation @@ -35,17 +33,16 @@ Installation $ pipenv install bqplot ipyvuetify voila-vuetify==voila-vuetify 0.0.1a8 -Verwendung -~~~~~~~~~~ +Usage +~~~~~ -Um ``voila-vuetify`` in einem Notebook zu verwenden, müsst ihr zunächst -``ipyvuetify`` importieren: +To use ``voila-vuetify`` in a notebook, you first have to import ``ipyvuetify``: .. code-block:: python import ipyvuetify as v -Anschließend könnt ihr ein Layout erstellen z.B mit: +Then you can create a layout, e.g. with: .. code-block:: python @@ -70,22 +67,21 @@ Anschließend könnt ihr ein Layout erstellen z.B mit: ]) ]) -:doc:`bqplot_vuetify_example`. könnt ihr nutzen mit: +You can use :doc:`bqplot_vuetify_example` with: .. code-block:: console $ pipenv run voila --template vuetify-default bqplot_vuetify_example.ipynb -Anschließend öffnet sich euer Standardbrowser mit der URL -``http://localhost:8866/`` und zeigt euch die Plots im Responsive Material -Design. +Then your standard browser will open the URL ``http://localhost:8866/`` and show +you the plots in Responsive Material Design. -Beispiel für Voilà-vuetify mit der Monitorauflösung eines Laptop MDPI-Screen: +Example for Voilà-vuetify with the monitor resolution of a laptop MDPI screen: .. image:: voila-vuetify-laptop.png :scale: 53% -Beispiel für Voilà-vuetify mit der Monitorauflösung eine iPhone X: +Example for Voilà-vuetify with the monitor resolution of an iPhone X: .. image:: voila-vuetify-iphone.png :scale: 53% @@ -93,8 +89,8 @@ Beispiel für Voilà-vuetify mit der Monitorauflösung eine iPhone X: voila-debug ----------- -`voila-debug `_ ist ein Template zum -Anzeigen von Debug-Informationen bei der Arbeit an Voilà-Anwendungen. +`voila-debug `_ is a template for +displaying debug information when working on Voilà applications. Installation ~~~~~~~~~~~~ @@ -103,26 +99,26 @@ Installation $ pipenv install voila-debug -Verwendung -~~~~~~~~~~ +Usage +~~~~~ -Ihr könnt das Template :doc:`debug.ipynb` nutzen mit: +You can use the template :doc:`debug.ipynb` with: .. code-block:: console $ pipenv run voila --template=debug --VoilaExporter.template_file=debug.tpl -Dies öffnet euren Standardbrowser mit der URL ``localhost:8866``. +This will open your default browser with the URL ``localhost:8866``. -In -``http://localhost:8866/voila/render/docs/jupyter/dashboards/voila/debug.ipynb`` -könnt ihr euch dann die Funktionsweise genauer anschauen. +Then you can take a closer look at how it works at +``http://localhost:8866/voila/render/docs/jupyter/dashboards/voila/debug.ipynb``. .. image:: voila-debug.png :scale: 53% - :alt: Beispiel für Voilà-Debug + :alt: Example of voila-debug -Es enthält neben einem Beispiel-Widget eine Code-Zelle zum Beenden des Kernels: +In addition to an example widget, it contains a code cell for exiting the +kernel: .. code-block:: python @@ -135,11 +131,11 @@ Es enthält neben einem Beispiel-Widget eine Code-Zelle zum Beenden des Kernels: button.on_click(kill_kernel) button -Eigene Templates erstellen --------------------------- +Create your own templates +------------------------- -Ein Voilà-Template ist ein Ordner, der sich im Virtual-environment unter -``share/jupyter/voila/templates`` befindet und z.B. Folgendes enthält: +A Voilà template is a folder that is located in the virtual environment at +``share/jupyter/voila/templates`` and for example, contains the following: .. code-block:: console @@ -158,15 +154,15 @@ Ein Voilà-Template ist ein Ordner, der sich im Virtual-environment unter └── tree.html ``conf.json`` - Konfigurationsdatei, die z.B. auf das Basis-Template verweist: + Configuration file that e.g. refers to the basic template: .. code-block:: json {"base_template": "default"} ``nbconvert_templates`` - Benutzerdefinierte Templates für :doc:`/workspace/jupyter/nbconvert`. + Custom templates for nbconvert :doc:`/workspace/jupyter/nbconvert`. ``static`` - Verzeichnis für statische Dateien. + Directory for static files. ``templates`` - Benutzerdefinierte Tornado-Templates. + Custom tornado templates. diff --git a/docs/web/index.rst b/docs/web/index.rst index 93d44651..f20b1b4f 100644 --- a/docs/web/index.rst +++ b/docs/web/index.rst @@ -1,14 +1,14 @@ -Web-Applikationen erstellen -=========================== +Create web applications +======================= -Im Folgenden stelle ich euch drei verschiedene Arten von Web-Anwendungen vor: +I will introduce you to three different types of web applications: -* aus Jupyter-Notebooks generierte :doc:`dashboards/index` -* über die Notebooks hinausgehende Web-Anwendungen, die z.B. Bokeh-Plots - einbinden, wie in :doc:`pyviz:bokeh/embedding-export/flask` demonstriert -* schließlich die Bereitstellung eurer Daten über eine `RESTful API - `_, z.B. - mit dem `FastAPI framework `_. +* :doc:`dashboards/index` generated from Jupyter notebooks +* Web applications that go beyond notebooks, such as integrating bokeh plots, as + demonstrated in :doc:`pyviz:bokeh/embedding-export/flask` +* Finally, the provision of your data via a `RESTful API + `_, e.g. with + the `FastAPI framework `_. .. toctree:: :hidden: diff --git a/docs/workspace/index.rst b/docs/workspace/index.rst index 3dc52857..e5891dd4 100644 --- a/docs/workspace/index.rst +++ b/docs/workspace/index.rst @@ -1,9 +1,9 @@ -Arbeitsbereich -============== +Workspace +========= -Das Einrichten des Arbeitsbereichs umfasst das Installieren und Konfigurieren -von :doc:`ipython/index` und :doc:`jupyter/index` mit -:doc:`jupyter/nbextensions/index` und :doc:`jupyter/ipywidgets/index`. +Setting up the workspace includes installing and configuring +:doc:`ipython/index` and :doc:`jupyter/index` with :doc:`jupyter/nbextensions/index` +and :doc:`jupyter/ipywidgets/index`. .. toctree:: :hidden: diff --git a/docs/workspace/ipython/debugging.ipynb b/docs/workspace/ipython/debugging.ipynb index f8d2194c..74bf0760 100644 --- a/docs/workspace/ipython/debugging.ipynb +++ b/docs/workspace/ipython/debugging.ipynb @@ -4,18 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Fehleranalyse\n", + "# Debugging\n", "\n", - "IPython enthält verschiedene Werkzeuge, um fehlerhaften Code zu analysieren, im Wesentlichen das *Exception Reporting* und den Debugger." + "IPython contains various tools to analyse faulty code, essentially the exception reporting and the debugger." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Exceptions kontrollieren mit `%xmode`\n", + "## Check exceptions with `%xmode`\n", "\n", - "Wenn die Ausführung eines Python-Skripts fehlschlägt, wird meist eine sog. *Exception* ausgelöst und relevante Informationen zur Fehlerursache in einen *Traceback* geschrieben. Mit der `%xmode`-Magic-Funktion könnt ihr in IPython die Menge der Informationen steuern, die euch angezeigt werden. Betrachten wir hierfür den folgenden Code:" + "If the execution of a Python script fails, a so-called exception is usually thrown and relevant information about the cause of the error is written to a traceback. With the `%xmode` magic function you can control the amount of information that is displayed in IPython. Let's look at the following code for this:" ] }, { @@ -60,14 +60,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der Aufruf von `func2`führt zu einem Fehler, und der `Traceback` zeigt genau, was passiert ist: in jeder Zeile wird der Kontext jedes Schritts angezeigt, der schließlich zum Fehler geführt hat. Mit der `%xmode`-Magic-Funktion (kurz für *Exception-Modus*) können wir steuern, welche Informationen uns angezeigt werden sollen.\n", + "Calling `func2` leads to an error and the traceback shows exactly what happened: each line shows the context of each step that ultimately led to the error. With the `%xmode` magic function (short for exception mode) we can control which information should be displayed to us.\n", "\n", - "`%xmode` nimmt ein einziges Argument, den Modus, und es gibt drei Möglichkeiten:\n", + "`%xmode` takes a single argument, the mode, and there are three options:\n", "* `Plain`\n", "* `Context`\n", "* `Verbose`\n", "\n", - "Die Standardeinstellung ist `Context` und gibt eine Ausgabe wie die obige aus. `Plain` ist kompakter und liefert weniger Informationen:" + "The default setting is `Context` and outputs something like the one above. `Plain` is more compact and provides less information:" ] }, { @@ -104,7 +104,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der `Verbose`-Modus zeigt einige zusätzliche Informationen an, einschließlich der Argumente für alle aufgerufenen Funktionen:" + "The `Verbose` mode shows some additional information, including the arguments for any functions being called:" ] }, { @@ -142,7 +142,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Diese zusätzlichen Informationen können helfen, den Grund für die *Exception* einzugrenzen. Umgekehrt kann der `Verbose`-Modus jedoch bei komplexem Code zu extrem langen Tracebacks führen, bei denen kaum noch die wesentlichen Stellen erkannt werden können." + "This additional information can help narrow down the reason for the exception. Conversely, however, the `Verbose` mode can lead to extremely long tracebacks in the case of complex code, in which the essential points can hardly be recognized." ] }, { @@ -151,11 +151,11 @@ "source": [ "## Debugging\n", "\n", - "Wenn durch das Lesen eines `Traceback` ein Fehler nicht gefunden werden kann, hilft Debugging weiter. Der Python-Standard für interaktives Debugging ist der Python-Debugger `pdb`. Mit ihm könnt ihr euch zeilenweise durch den Code navigieren, um festzustellen, was möglicherweise einen Fehler verursacht. Die erweiterte Version für IPython ist `ipdb`.\n", + "Debugging can help if an error cannot be found by reading a traceback. The Python standard for interactive debugging is the Python debugger `pdb`. You can use it to navigate your way through the code line by line to see what is possibly causing an error. The extended version for IPython is `ipdb`.\n", "\n", - "In IPython ist der `%debug`-Magic-Befehl möglicherweise die bequemste Art zum Debugging. Wenn ihr ihn aufruft, nachdem eine Exception ausgegeben wurde, wird automatisch ein interaktiver Debug-Prompt während der Exception geöffnet. Mit der `ipdb`-Eingabeaufforderung könnt ih den aktuellen Status des Stacks untersuchen, die verfügbaren Variablen untersuchen und sogar Python-Befehle ausführen.\n", + "In IPython, the `%debug`-magic command is perhaps the most convenient way to debug. If you call it after an exception has been thrown, an interactive debug prompt will automatically open during the exception. Using the `ipdb` prompt, you can examine the current status of the stack, examine the available variables and even run Python commands.\n", "\n", - "Schauen wir uns die letzte Exception an und führen dann einige grundlegende Aufgaben aus:" + "Let's look at the last exception, then do some basic tasks:" ] }, { @@ -190,7 +190,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der interaktive Debugger bietet jedoch viel mehr – wir können im Stack auch auf und ab gehen und die Werte von Variablen untersuchen:" + "However, the interactive debugger does a lot more – we can also go up and down the stack and examine the values of variables:" ] }, { @@ -244,9 +244,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dies vereinfacht die Suche nach den Funktionsaufrufen, die zum Fehler geführt haben, enorm.\n", + "This greatly simplifies the search for the function calls that led to the error.\n", "\n", - "Wenn der Debugger automatisch gestartet werden soll, wenn eine Ausnahme ausgelöst wird, könnt ihr die `%pdb`-Magic-Funktion verwenden, um dieses Verhalten zu aktivieren:" + "If you want the debugger to start automatically when an exception is thrown, you can use the `%pdb`-magic function to enable this behavior:" ] }, { @@ -301,33 +301,33 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wenn ihr ein Skript habt, das ihr von Anfang an im interaktiven Modus ausführen möchtet, so könnt ihr dies mit dem Befehl `%run -d`." + "If you have a script that you want to run in interactive mode from the start, you can do so with the command `%run -d`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Wesentliche Befehle des `ipdb`\n", + "### Essential commands of the `ipdb`\n", "\n", - "| Befehl | Beschreibung |\n", + "| Command | Description |\n", "| -------------- | ------------------------------------------------------------------------- |\n", - "| `list` | Zeige den aktuellen Ort in der Datei |\n", - "| `h`(`elp`) | Liste der Befehle anzeigen oder Hilfe zu einem bestimmten Befehl suchen |\n", - "| `q`(`uit`) | Beendet den Debugger und das Programm |\n", - "| `c`(`ontinue`) | Den Debugger beenden, im Programm fortfahren |\n", - "| `n`(`ext`) | Gehe zum nächsten Schritt des Programms |\n", - "| `` | Wiederhole den vorherigen Befehl |\n", - "| `p`(`rint`) | Druckvariablen |\n", - "| `s`(`tep`) | Schritt in eine Unterroutine |\n", - "| `r`(`eturn`) | Rückkehr aus einem Unterprogramm |\n" + "| `list` | Show the current location in the file |\n", + "| `h`(`elp`) | Display a list of commands or find help on a specific command |\n", + "| `q`(`uit`) | Terminates the debugger and the program |\n", + "| `c`(`ontinue`) | Exit the debugger, continue in the program |\n", + "| `n`(`ext`) | Go to the next step in the program |\n", + "| `` | Repeat the previous command |\n", + "| `p`(`rint`) | Print variables |\n", + "| `s`(`tep`) | Step into a subroutine |\n", + "| `r`(`eturn`) | Return from a subroutine |\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Weitere Informationen zum IPython-Debugger erhaltet ihr unter [ipdb](https://github.com/gotcha/ipdb)." + "Further information on the IPython debugger can be found at [ipdb](https://github.com/gotcha/ipdb)." ] } ], diff --git a/docs/workspace/ipython/display.ipynb b/docs/workspace/ipython/display.ipynb index dab6796b..cfabb39b 100644 --- a/docs/workspace/ipython/display.ipynb +++ b/docs/workspace/ipython/display.ipynb @@ -4,18 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Objekte anzeigen mit `display`\n", + "# Show objects with `display`\n", "\n", - "IPython kann Objekte anzeigen wie z.B. `HTML`, `JSON`, `PNG`, `JPEG`, `SVG` und `Latex`. " + "IPython can display objects such as `HTML`, `JSON`, `PNG`, `JPEG`, `SVG` and `Latex`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Bilder\n", + "## Images\n", "\n", - "Um Bilder (`JPEG`, `PNG`) in IPython und Notebooks anzuzeigen, könnt ihr die `Image`-Klasse verwenden:" + "To display images (`JPEG`, `PNG`) in IPython and notebooks, you can use the `Image` class:" ] }, { @@ -96,21 +96,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Nicht-eingebettete Bilder\n", + "### Non-embedded images\n", "\n", - "* Standardmäßig sind Bilddaten eingebettet:\n", + "* By default, image data is embedded:\n", "\n", " ```\n", " Image ('img_url')\n", " ```\n", "\n", - "* Wenn jedoch `url` als `kwarg` angegeben ist, wird dies als *Softlink* interpretiert:\n", + "* However, if the `url` is given as `kwarg`, this is interpreted as a soft link:\n", "\n", " ```\n", " Image (url='img_url')\n", " ```\n", "\n", - "* `embed` kann jedoch auch explizit angegeben werden: \n", + "* `embed` can also be specified explicitly:\n", "\n", " ```\n", " Image (url='img_url', embed = True)\n", @@ -123,7 +123,7 @@ "source": [ "## HTML\n", "\n", - "Python-Objekte können HTML-Repräsentationen deklarieren, die in einem Notebook angezeigt werden:" + "Python objects can declare HTML representations to be displayed in a notebook:" ] }, { @@ -170,7 +170,7 @@ "source": [ "## Javascript\n", "\n", - "Mit Notebooks können Objekte auch eine JavaScript-Darstellung deklarieren. Dies ermöglicht dann z.B. Datenvisualisierungen mit Javascript-Bibliotheken wie [d3.js](https://d3js.org/)." + "With notebooks, objects can also declare a JavaScript representation. This enables e.g. data visualisations with Javascript libraries like [d3.js](https://d3js.org/)." ] }, { @@ -201,7 +201,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Für umfangreicheres Javascript könnt ihr auch die `%%javascript`-Syntax verwenden." + "For more extensive Javascript you can also use the `%%javascript` syntax." ] }, { @@ -210,7 +210,7 @@ "source": [ "## LaTeX\n", "\n", - "`IPython.display` verfügt außerdem über eine integrierte Unterstützung für die Anzeige von mathematischen Ausdrücken, die in LaTeX gesetzt sind und im Browser mit [MathJax](http://mathjax.org/) gerendert werden:" + "`IPython.display` also has built-in support for displaying mathematical expressions set in LaTeX and rendered in the browser with [MathJax](http://mathjax.org/):" ] }, { @@ -241,7 +241,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Bei der `Latex`-Klasse müsst ihr die Begrenzungen selbst angeben. Auf diese Weise könnt ihr jedoch auch andere LaTeX-Modi verwenden, wie z.B. `eqnarray`:" + "With the `Latex` class you have to specify the limits yourself. In this way, however, you can also use other LaTeX modes, such as `eqnarray`:" ] }, { @@ -278,7 +278,7 @@ "source": [ "## Audio\n", "\n", - "IPython ermöglicht auch das interaktive Arbeiten mit Sounds. Mit der `display.Audio`-Klasse könnt ihr ein Audio-Control erstellen, das in das Notebook eingebettet ist. Die Schnittstelle ist analog zu denjenigen der `Image`-Klasse. Alle vom Browser unterstützten Audioformate können verwendet werden." + "IPython also enables interactive work with sounds. With the `display.Audio` class you can create an audio control that is embedded in the notebook. The interface is analogous to that of the `Image` class. All audio formats supported by the browser can be used." ] }, { @@ -294,7 +294,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Im folgenden werden wir die Sinusfunktion eines NumPy-Array als Audiosignal ausgeben. Dabei normalisiert und codiert die `Audio`-Klasse die Daten und bettet das resultierende Audio in das Notebook ein." + "In the following we will output the sine function of a NumPy array as an audio signal. The `Audio` class normalises and codes the data and embeds the resulting audio in the notebook." ] }, { @@ -336,9 +336,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Links zu lokalen Dateien\n", + "## Links to local files\n", "\n", - "IPython bietet integrierte Klassen zum Generieren von Links zu lokalen Dateien. Erstellt hierzu eine Verknüpfung zu einer einzelnen Datei mit dem `FileLink`-Objekt:" + "IPython has built-in classes for generating links to local files. To do this, create a link to a single file with the `FileLink` object:" ] }, { @@ -369,7 +369,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ könnt ihr auch eine Liste mit Links zu allen Dateien in einem Verzeichnis generieren, z.B.:" + "Alternatively, you can generate a list with links to all files in a directory, e.g .:" ] }, { @@ -417,7 +417,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Notebooks anzeigen" + "## Display notebooks" ] }, { diff --git a/docs/workspace/ipython/extensions.rst b/docs/workspace/ipython/extensions.rst index 1b41cc09..e3ce7d32 100644 --- a/docs/workspace/ipython/extensions.rst +++ b/docs/workspace/ipython/extensions.rst @@ -1,32 +1,31 @@ -IPython-Erweiterungen -===================== +IPython extensions +================== -IPython-Erweterungen sind Python-Module, die das Verhalten der Shell ändern. Sie -werden mit einem importierbaren Modulnamen bezeichnet und befinden sich -üblicherweise in ``.ipython/extensions/``. +IPython extensions are Python modules that change the behavior of the shell. +They are identified by an importable module name and are usually located in +``.ipython/extensions/``. -Einige wichtige Erweiterungen sind bereits in IPython enthalten: -:label:`extensions_autoreload` und :label:`extensions_storemagic`. Andere -Erweiterungen findet ihr im `Extensions Index -`_ oder auf PyPI unter -dem `IPython tag `_. +Some important extensions are already included in IPython: +:label:`extensions_autoreload` and :label:`extensions_storemagic`. You can find +other extensions in the `Extensions Index +`_ or on PyPI with +the `IPython tag `_.. .. seealso:: * `IPython extensions docs `_ -Erweiterungen verwenden ------------------------ +Use extensions +-------------- -Die ``%load_ext``-Magie kann verwendet werden um Erweiterungen zu laden während -IPython ausgeführt wird. +The ``%load_ext`` magic can be used to load extensions while IPython is running. .. code-block:: ipython %load_ext myextension -Alternativ kann eine Erweiterung auch bei jedem Start von IPython geladen -werden, indem sie in der IPython-Konfigurationsdate aufgelistet wird: +Alternatively, an extension can also be loaded each time IPython is started by +listing it in the IPython configuration file: .. code-block:: Python @@ -34,24 +33,22 @@ werden, indem sie in der IPython-Konfigurationsdate aufgelistet wird: 'myextension' ] -Falls ihr noch keine IPython-Konfigurationsdatei erstellt habt, könnt ihr dies -mit: +If you haven’t created an IPython configuration file yet, you can do this with: .. code-block:: console $ ipython profile create [profilename] -Falls kein Profilname angegeben wird, wird ``default`` verwendet. Üblicherweise -wird die Datei dann in ``~/.ipython/profile_default/`` erstellt und je nach -Verwendungszweck benannt: ``ipython_config.py`` wird für alle IPython-Befehle -verwendet, während ``ipython_notebook_config.py`` nur für Befehle in -IPython-Notebooks Verwendung findet. +If no profile name is given, ``default` is used. The file is usually created in +``~/.ipython/profile_default/`` and named depending on the purpose: +``ipython_config.py`` is used for all IPython commands, while +``ipython_notebook_config.py`` is only used for commands in IPython notebooks. -IPython-Erweiterungen schreiben -------------------------------- +Writing IPython extensions +-------------------------- -Eine IPython-Erweiterung ist ein importierbares Python-Modul, das über spezielle -Funktionen zum Laden und Entladen verfügt: +An IPython extension is an importable Python module that has special functions +for loading and unloading: .. code-block:: python diff --git a/docs/workspace/ipython/importing.ipynb b/docs/workspace/ipython/importing.ipynb index ca5e80d7..85d82db2 100644 --- a/docs/workspace/ipython/importing.ipynb +++ b/docs/workspace/ipython/importing.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Notebooks importieren\n", + "# Import notebooks\n", "\n", - "Um modularer entwickeln zu können, ist der Import von Notebooks erforderlich. Da Notebooks jedoch keine Python-Dateien sind, lassen sie sich auch nicht so einfach importieren. Glücklicherweise stellt Python einige Hooks für den Import bereit, sodass IPython-Notebooks schließlich doch importiert werden können." + "To be able to develop more modularly, the import of notebooks is necessary. However, since notebooks are not Python files, they are not easy to import. Fortunately, Python provides some hooks for the import so that IPython notebooks can eventually be imported." ] }, { @@ -34,12 +34,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Import-Hooks haben normalerweise zwei Objekte:\n", + "Import hooks usually have two objects:\n", "\n", - "* **Module Loader**, der einen Modulnamen (z. B. `IPython.display`) annimmt und ein Modul zurückgibt\n", - "* **Module Finder**, der herausfindet, ob ein Modul vorhanden ist, und Python mitteilt, welcher *Loader* verwendet werden soll\n", + "* **Module Loader** that takes a module name (e.g. `IPython.display`) and returns a module\n", + "* **Module Finder**, which finds out if a module is present and tells Python which *loader* to use\n", "\n", - "Zunächst jedoch schreiben wir eine Methode, die ein Notebook anhand des vollständig qualifizierten Namen und des optionalen Pfades findet. So wird z.B. aus `mypackage.foo` `mypackage/foo.ipynb` und ersetzt `Foo_Bar` durch `Foo Bar`, wenn `Foo_Bar` nicht existiert." + "But first, let’s write a method that a notebook will find using the fully qualified name and the optional path. E.g. `mypackage.foo` becomes `mypackage/foo.ipynb` and replaces `Foo_Bar` with `Foo Bar` if `Foo_Bar` doesn’t exist." ] }, { @@ -68,13 +68,13 @@ "source": [ "## Notebook Loader\n", "\n", - "Der Notebook Loader führt die folgenden drei Schritte aus:\n", + "The Notebook Loader does the following three steps:\n", "\n", - "1. Laden des Notebook-Dokuments in den Speicher\n", - "2. Erstellen eines leeren Moduls\n", - "3. Ausführen jeder Zelle im Modul-Namensraum\n", + "1. Load the notebook document into memory\n", + "2. Create an empty module\n", + "3. Execute every cell in the module namespace\n", "\n", - " Da IPython-Zellen eine erweiterte Syntax haben können, wird mit `transform_cell` jede Zelle in reinen Python-Code umgewandelt, bevor er ausgeführt wird.\n" + " Because IPython cells can have an extended syntax, `transform_cell` converts each cell to pure Python code before executing it." ] }, { @@ -132,7 +132,7 @@ "source": [ "## Notebook Finder\n", "\n", - "Der Finder ist ein einfaches Objekt, das angibt, ob ein Notebook anhand seines Dateinamens importiert werden kann, und das den entsprechenden Loader zurückgibt. " + "The Finder is a simple object that indicates whether a notebook can be imported based on its file name and that returns the appropriate loader." ] }, { @@ -165,9 +165,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Hook registrieren\n", + "## Register hook\n", "\n", - "Jetzt registrieren wir `NotebookFinder` mit `sys.meta_path`:" + "Now we register `NotebookFinder` with `sys.meta_path`:" ] }, { @@ -183,14 +183,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Überprüfen" + "## Check" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Nun sollte unser Notebook [mypackage/foo.ipynb](mypackage/foo.ipynb) importierbar sein mit" + "Now our notebook [mypackage/foo.ipynb](mypackage/foo.ipynb) should be importable with:" ] }, { @@ -214,7 +214,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wird die Python-Methode `bar` ausgeführt?" + "Is the Python method `bar` being executed?" ] }, { @@ -241,7 +241,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "… und die IPython-Syntax?" + "… and the IPython syntax?" ] }, { @@ -279,9 +279,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Wiederverwendbarer Import-Hook\n", + "## Reusable import hook\n", "\n", - "Der Import-Hook kann auch einfach in anderen Notebooks ausgeführt werden mit" + "The import hook can also easily be executed in other notebooks with" ] }, { diff --git a/docs/workspace/ipython/index.rst b/docs/workspace/ipython/index.rst index fa5283d3..6caa761e 100644 --- a/docs/workspace/ipython/index.rst +++ b/docs/workspace/ipython/index.rst @@ -1,13 +1,12 @@ IPython ======= -`IPython `_ oder *Interactive Python* war zunächst ein -erweiterter Python-Interpreter, der nun zu einem umfangreichen Projekt geworden -ist, das Tools für den gesamten Lebenszyklus der Forschungsdatenverarbeitung -bereitstellen soll. So ist IPython heute nicht nur eine interaktive -Schnittstelle zu Python, sondern bietet auch eine Reihe nützlicher syntaktischer -Ergänzungen für die Sprache. Darüberhinaus ist IPython eng mit dem -`Jupyter-Projekt `_ verbunden. +`IPython `_, or *Interactive Python*, was initially an +advanced Python interpreter that has now grown into an extensive project +designed to provide tools for the entire life cycle of research computing. +Today, IPython is not only an interactive interface to Python, but also offers a +number of useful syntactic additions for the language. In addition, IPython is +closely related to the `Jupyter project `_. .. toctree:: :hidden: diff --git a/docs/workspace/ipython/magics.ipynb b/docs/workspace/ipython/magics.ipynb index 9b2e96e5..3b357956 100644 --- a/docs/workspace/ipython/magics.ipynb +++ b/docs/workspace/ipython/magics.ipynb @@ -4,23 +4,23 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# IPython-Magie\n", + "# IPython magic\n", "\n", - "IPython ermöglicht nicht nur Python interaktiv zu verwenden, sondern erweitert auch die Python-Syntax um sog. *Magic Commands*, die mit dem Präfix `%` versehen werden. Sie wurden entwickelt, um häufig auftretende Probleme bei der Datenanalyse schnell und einfach lösen zu können. Dabei wird zwischen zwei verschiedenen Arten von *Magic Commands* unterschieden:\n", + "IPython not only enables Python to be used interactively, but also extends the Python syntax with so-called *magic commands*, which are provided with the prefix `%`. They are designed to quickly and easily solve common data analysis problems. A distinction is made between two different types of *magic commands*:\n", "\n", - "* *line magics*, die durch einen einzelnen `%`-Präfix gekennzeichnet sind und auf einer einzelnen Eingabezeile ausgeführt werden\n", - "* *cell magics*, denen ein doppeltes Symbol `%%` vorangestellt wird und die innerhalb einer Notebook-Zelle ausgeführt werden." + "* *line magics*, denoted by a single `%` prefix, that run on a single input line\n", + "* *cell magics* which are preceded by a double symbol `%%` and which are executed within a notebook cell." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Externen Code ausführen: `%run`\n", + "## Execute external code: `%run`\n", "\n", - "Wenn ihr anfangt, umfangreicheren Code zu entwickeln, arbeitet ihr vermutlich sowohl in IPython für interaktive Erkundungen als auch in einem Texteditor zum Speichern von Code, den ihr wiederverwenden möchtet. Mit der `%run`-Magie könnt ihr diesen Code direkt in eurer IPython-Sitzung ausführen.\n", + "If you start developing larger code, you will likely be working in both IPython for interactive exploration and a text editor to save code that you want to reuse. With the `%run` magic you can execute this code directly in your IPython session.\n", "\n", - "Stellt euch vor, ihr hättet eine `myscript.py`-Datei mit folgendem Inhalt erstellt:\n", + "Imagine you created a `myscript.py` file with the following content:\n", "\n", "``` Python\n", "def square(x):\n", @@ -54,7 +54,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Beachtet, dass nach dem Ausführen dieses Skripts alle darin definierten Funktionen für die Verwendung in eurer IPython-Sitzung verfügbar sind:" + "Note that after running this script, all of the functions defined in it will be available for use in your IPython session:" ] }, { @@ -81,16 +81,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Es gibt verschiedene Möglichkeiten, die Ausführung eures Codes zu verbessern. Wie üblich, könnt ihr euch die Dokumentation in IPython anzeigen lassen mit `%run?`." + "There are several ways you can improve the way your code runs. As usual, you can display the documentation in IPython with `%run?`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Timing-Code ausführen: `%timeit`\n", + "## Run timing code: `%timeit`\n", "\n", - "Ein weiteres Beispiel für eine Magic-Funktion ist `%timeit`, die automatisch die Ausführungszeit der darauf folgenden einzeiligen Python-Anweisung ermittelt. So können wir uns z.B. die Performance einer *list comprehension* ausgeben lassen mit:" + "Another example of a Magic function is `%timeit`, which automatically determines the execution time of the following one-line Python statement. So we can e.g. output the performance of a list comprehension with:" ] }, { @@ -114,7 +114,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der Vorteil von `%timeit` ist, dass bei kurzen Befehlen automatisch mehrere Läufe ausgeführt werden, um robustere Ergebnisse zu erzielen. Bei mehrzeiligen Anweisungen wird durch Hinzufügen eines zweiten `%`-Zeichens eine Zellenmagie erzeugt, die mehrere Eingabezeilen verarbeiten kann. Hier ist zum Beispiel die äquivalente Konstruktion mit einer `for`-Schleife:" + "The advantage of `%timeit` is that short commands automatically run multiple runs to get more robust results. For multi-line instructions, adding a second `%` character creates cell magic that can process multiple input lines. For example, here is the equivalent construction using a `for` loop:" ] }, { @@ -141,16 +141,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir können sofort erkennen, dass die *list comprehension* etwa 10% schneller ist als das entsprechende Äquivalent mit einer `for` Schleife. Ausführlicher beschreiben wir Performance-Messungen und -Optimierungen dann in [Profiling](profiling.ipynb)." + "We can immediately see that the list comprehension is about 10% faster than its equivalent with a `for` loop. We then describe performance measurements and optimisations in more detail in [Profiling](profiling.ipynb)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Code anderer Interpreter ausführen\n", + "## Execute code from other interpreters\n", "\n", - "IPython verfügt über eine `%%script`-Magie, mit der ihr eine Zelle in einem Unterprozess eines Interpreters auf eurem System ausführen könnt, z.B. `bash`, `ruby`, `perl`, `zsh`, `R` usw. Dies kann auch ein eigenes Skript sein, das Eingaben in ` stdin` erwartet. Hierzu wird einfach eine Pfadangabe oder ein Shell-Befehl an das Programm übergeben, das in der `%%script`-Zeile angegeben ist. Der Rest der Zelle wird von diesem Skript ausgeführt, `stdout` oder `err` aus dem Unterprozess erfasst und angezeigt." + "IPython has a `%%script` script magic with which you can execute a cell in a subprocess of an interpreter on your system, e.g. `bash`, `ruby`, `perl`, `zsh`, `R` etc. This can also be its own script that expects input in `stdin`. To do this, simply pass a path or a shell command to the program that is specified in the `%%script` line. The rest of the cell is executed by this script, capturing `stdout` or `err` from the subprocess and displaying it." ] }, { @@ -233,7 +233,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Ihr könnt `stdout` und `err` aus diesen Unterprozessen in Python-Variablen erfassen:" + "You can capture `stdout` and `err` from these sub-processes in Python variables:" ] }, { @@ -272,9 +272,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Standard-`script`-Magie konfigurieren\n", + "## Configure standard `script` magic\n", "\n", - "Die Liste der Aliase für die `script`-Magie ist konfigurierbar. Standardmäßig können ggf. einige gängige Interpreter verwendet werden. Ihr könnt jedoch in `ipython_config.py` auch eigene Interpreter angeben:\n", + "The list of aliases for the `script` magic is configurable. By default, some common interpreters can be used if necessary. However, you can also specify your own interpreter in `ipython_config.py`:\n", "```\n", "c.ScriptMagics.scripts = ['R', 'pypy', 'myprogram']\n", "c.ScriptMagics.script_paths = {'myprogram': '/path/to/myprogram'}\n", @@ -285,9 +285,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Hilfe-Funktionen: `?`, `%magic` und `%lsmagic`\n", + "## Help functions: `?`, `%magic` and `%lsmagic`\n", "\n", - "Wie normale Python-Funktionen verfügen auch die magischen IPython-Funktionen über *docstrings*, auf die einfach zugegriffen werden können. Um z.B. die Dokumentation der `%timeit`-Magie zu lesen, gebt einfach Folgendes ein:" + "Like normal Python functions, the IPython magic functions have docstrings that can be easily accessed. E.g. to read the documentation of the `%timeit` magic, just type:" ] }, { @@ -303,7 +303,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Auf die Dokumentation für andere Funktionen kann auf ähnliche Weise zugegriffen werden. Um auf eine allgemeine Beschreibung der verfügbaren `%magic`-Funktionen einschließlich einiger Beispiele zuzugreifen, könnt ihr Folgendes eingeben:" + "Documentation for other functions can be accessed in a similar manner. To access a general description of the `%magic` functions available, including some examples, you can type:" ] }, { @@ -319,7 +319,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Um schnell eine Liste aller verfügbaren `magic`-Funktionen zu erhalten, gebt Folgendes ein:" + "For a quick list of all available `magic` functions, type:" ] }, { @@ -484,7 +484,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Ihr könnt auch einfach eure eigenen `magic`-Funktionen definieren. Weitere Informationen hierzu erhaltet ihr unter [Defining custom magics](https://ipython.readthedocs.io/en/stable/config/custommagics.html)." + "You can also simply define your own `magic` functions. For more information, see [Defining custom magics](https://ipython.readthedocs.io/en/stable/config/custommagics.html)." ] } ], diff --git a/docs/workspace/ipython/profiling.ipynb b/docs/workspace/ipython/profiling.ipynb index fdbfd80e..1c693f35 100644 --- a/docs/workspace/ipython/profiling.ipynb +++ b/docs/workspace/ipython/profiling.ipynb @@ -6,31 +6,32 @@ "source": [ "# Profiling\n", "\n", - "Bei der Entwicklung von Code kann es häufig zu Kompromissen zwischen verschiedenen Implementierungen kommen. Zu Beginn der Entwicklung eines Algorithmus ist es jedoch meist kontraproduktiv, sich um die Effizienz des Codes zu kümmern. \n", + "Often, when developing code, there can be trade-offs between different implementations. However, at the beginning of the development of an algorithm, it is usually counterproductive to worry about the efficiency of the code.\n", + "\n", "\n", "> *«We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%.»* – Donald Knuth in Computer Programming as an Art (1974)\n", "\n", - "Wenn ihr aber erst einmal mit eurem Code gearbeitet habt, kann es nützlich sein, die Effizienz genauer zu untersuchen. IPython bietet Zugriff auf eine breite Palette von Funktionen um die Zeiten zu messen und Profile zu erstellen. Hier werden die folgenden magischen IPython-Befehle erläutert:\n", + "However, once you’ve worked with your code, it can be useful to take a closer look at its efficiency. IPython provides access to a wide range of functions for measuring times and creating profiles. Here are the following magical IPython commands:\n", "\n", - "| Befehl | Beschreibung |\n", + "| Command | Description |\n", "| -------------- | --------------------------------------------------------------------------------- |\n", - "| `%time` | Zeit für die Ausführung einer einzelnen Anweisung |\n", - "| `%timeit` | Durchschnittliche Zeit für die wiederholte Ausführung einer einzelnen Anweisung |\n", - "| `%prun` | Code mit dem Profiler ausführen |\n", - "| `%lprun` | Code mit dem zeilenweisen Profiler ausführen |\n", - "| `%memit` | Messen der Speichernutzung einer einzelnen Anweisung |\n", - "| `%mprun` | Führt den Code mit dem zeilenweisen Memory-Profiler aus |\n", + "| `%time` | Time to execute a single statement |\n", + "| `%timeit` | Average time it took to execute a single statement repeatedly |\n", + "| `%prun` | Run code with the profiler |\n", + "| `%lprun` | Run code with the line-by-line profiler |\n", + "| `%memit` | Measure the memory usage of a single statement |\n", + "| `%mprun` | Executes the code with the line-by-line memory profiler |\n", "\n", - "Die letzten vier Befehle sind nicht in IPython selbst, sondern in den Modulen [line_profiler](https://github.com/rkern/line_profiler) und [memory_profiler](https://github.com/pythonprofilers/memory_profiler) enthalten." + "The last four commands are not contained in IPython itself, but in the modules [line_profiler](https://github.com/rkern/line_profiler) and [memory_profiler](https://github.com/pythonprofilers/memory_profiler)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## `%timeit` und `%time`\n", + "## `%timeit` and `%time`\n", "\n", - "Wir haben die `%timeit`Zeilen- und `%%timeit`-Zellmagie bereits in der Einführung der magischen Funktionen in IPython Magic Commands gesehen. Sie können für Zeitmessungen bei der wiederholten Ausführung von Code-Schnipseln verwendet werden:" + "We saw the `%timeit` line and `%%timeit` cell magic in the introduction of the magic functions in IPython magic commands. They can be used to measure the timing of the repeated execution of code snippets:" ] }, { @@ -54,7 +55,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Beachtet, dass `%timeit` die Ausführung mehrfach in einer Schleife (`loops`) ausführt. Wenn mit `-n` nicht die Anzahl der Schleifen festgelegt wird, passt `%timeit` die Anzahl automatisch so an, dass ein ausreichende Messgenauigkeit erreicht wird:" + "Note that `%timeit` executes the execution multiple times in a loop. If the number of loops is not specified with `-n`, `%timeit` automatically adjusts the number so that sufficient measurement accuracy is achieved:" ] }, { @@ -82,7 +83,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Manchmal ist das Wiederholen einer Operation nicht die beste Option, z.B. wenn wir eine Liste haben, die wir sortieren möchten. Hier werden wir möglicherweise durch eine wiederholte Operation in die Irre geführt. Das Sortieren einer vorsortierten Liste ist viel schneller als das Sortieren einer unsortierten Liste, sodass die Wiederholung das Ergebnis verzerrt:" + "Sometimes repeating an operation is not the best option, e.g. when we have a list that we want to sort. Here we may be misled by repeated surgery. Sorting a presorted list is much faster than sorting an unsorted list, so repeating it distorts the result:" ] }, { @@ -109,7 +110,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Dann ist die `%time`-Funktion möglicherweise die bessere Wahl. Auch bei länger laufenden Befehlen, wenn kurze systembedingte Verzögerungen das Ergebnis wahrscheinlich kaum beeinflussen, dürfte `%time` die bessere Wahl sein:" + "Then the `%time` function might be a better choice. `%time` should also be the better choice for long-running commands, when short system-related delays are unlikely to affect the result:" ] }, { @@ -136,7 +137,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Sortieren einer bereits sortierten Liste:" + "Sorting an already sorted list:" ] }, { @@ -161,18 +162,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Beachtet, wie viel schneller die vorsortierte Liste zu sortieren ist, aber beachtet auch, wie viel länger das Timing mit `%time` gegenüber `%timeit` dauert, sogar für die vorsortierte Liste. Dies ist auf die Tatsache zurückzuführen, dass `%timeit` einige clevere Dinge unternimmt, um zu verhindern, dass Systemaufrufe die Zeitmessung stören. So wird beispielsweise die *Garbage Collection* nicht mehr verwendeter Python-Objekte verhindert, die sich andernfalls auf die Zeitmessung auswirken könnten. Aus diesem Grund sind die `%timeit`-Ergebnisse normalerweise merklich schneller als die `%time`-Ergebnisse." + "Note how much faster the pre-sorted list is to be sorted, but also note how much longer the timing with `%time` takes compared to `%timeit`, even for the pre-sorted list. This is due to the fact that `%timeit` is doing some clever things to keep system calls from interfering with the timing. This prevents, for example, the garbage collection of Python objects that are no longer used and that could otherwise affect the time measurement. Because of this, the `%timeit` results are usually noticeably faster than the `%time` results." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Profilerstellung für Skripte: `%prun`\n", + "## Profiling for scripts: `%prun`\n", "\n", - "Ein Programm besteht aus vielen einzelnen Anweisungen, und manchmal ist es wichtiger, diese Anweisungen im Kontext zu messen, als sie selbst zu messen. Python enthält einen integrierten [Code-Profiler](https://docs.python.org/3/library/profile.html). IPython bietet jedoch eine wesentlich bequemere Möglichkeit, diesen Profiler in Form der Magic-Funktion zu verwenden: `%prun`.\n", + "A program is made up of many individual instructions, and sometimes it is more important to measure those instructions in context than to measure them yourself. Python includes a built-in [Code-Profiler](https://docs.python.org/3/library/profile.html). However, IPython offers a much more convenient way to use this profiler in the form of the magic function `%prun`.\n", "\n", - "Als Beispiel definieren wir eine einfache Funktion, die einige Berechnungen durchführt:" + "As an example, let’s define a simple function that does some calculations:" ] }, { @@ -210,7 +211,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Im Notebook sieht die Ausgabe ungefähr so aus:\n", + "In the notebook the output looks something like this:\n", "\n", "```\n", "14 function calls in 9.597 seconds\n", @@ -231,35 +232,35 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Ergebnis ist eine Tabelle, die sortiert nach Gesamtzeit für jeden Funktionsaufruf die Ausführungsdauer angibt. In diesem Fall wird die meiste Zeit mit *List Comprehension* innerhalb von `sum_of_lists` verbraucht. Dies gibt uns Anhaltspunkte, an welcher Stelle wir die Effizienz des Algorithmus verbessern könnten." + "The result is a table that shows the execution time for each function call, sorted by total time. In this case, most of the time is consumed with list comprehension within `sum_of_lists`. This gives us clues as to where we could improve the efficiency of the algorithm." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Zeilenweise Profilerstellung: `%lprun`\n", + "## Profiling line by line: `%lprun`\n", "\n", - "Die Profilerstellung von `%prun` ist nützlich, aber manchmal ist ein zeilenweiser Profilreport aufschlussreicher. Dies ist nicht in Python oder IPython integriert, aber mit [line_profiler](https://github.com/rkern/line_profiler) steht ein Paket zur Verfügung, das dies ermöglicht. Diese kann in eurem Kernel bereitgestellt werden mit\n", + "Profiling with `%prun` is useful, but sometimes a line-by-line profile report is more insightful. This isn’t built into Python or IPython, but there is a package available, [line_profiler](https://github.com/rkern/line_profiler), that enables this. This can be provided in your kernel with\n", "\n", "```\n", "$ spack env activate python-374\n", "$ spack install py-line-profiler ^python@3.7.4%gcc@9.1.0\n", "```\n", "\n", - "Alternativ könnt ihr `line-profiler` auch mit anderen Paketmanagern installieren, z.B.\n", + "Alternatively, you can install `line-profiler` with other package managers, e.g.\n", "\n", "```\n", "$ pipenv install line_profiler\n", "```\n", "\n", - "Falls Ihr Python 3.7.x verwendet und die Fehlermeldung bekommt `error: command 'clang' failed with exit status 1`, bleibt aktuell nur, `Cython` zusammen mit den Ressourcen aus dem Git-Repository zu installieren:\n", + "If you are using Python 3.7.x and get the error message `error: command 'clang' failed with exit status 1`, the only thing left for now is to install Cython together with the resources from the Git repository:\n", "\n", "```\n", "$ pipenv install Cython git+https://github.com/rkern/line_profiler.git#egg=line_profiler\n", "```\n", "\n", - "Nun könnt ihr IPython mit der `line_profiler`-Erweiterung laden:" + "Now you can load IPython with the `line_profiler` extension:" ] }, { @@ -275,7 +276,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Der `%lprun`-Befehl führt eine zeilenweise Profilerstellung für jede Funktion durch. In diesem Fall muss explizit angegeben werden, welche Funktionen für die Profilerstellung interessant sind:" + "The `%lprun` command profiles each function line by line. In this case, you must explicitly specify which functions are of interest for creating the profile:" ] }, { @@ -291,7 +292,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Das Ergebnis sieht ungefähr so aus:\n", + "The result looks something like this:\n", "\n", "```\n", "Timer unit: 1e-06 s\n", @@ -315,25 +316,25 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Die Zeit wird in Mikrosekunden angegeben und wir können sehen, in welcher Zeile die Funktion die meiste Zeit verbringt. Eventuell können wir das Skript dann so ändern, dass die Effizienz der Funktion gesteigert werden kann.\n", + "The time is given in microseconds and we can see which line the function spends most of its time on. We may then be able to modify the script in such a way that the efficiency of the function can be increased.\n", "\n", - "Weitere Informationen zu `%lprun` sowie die verfügbaren Optionen findet ihr in der IPython-Hilfefunktion `%lprun?`." + "More information about `%lprun` and the available options can be found in the IPython help function `%lprun?`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Speicherprofil erstellen: `%memit` und `%mprun`\n", + "## Create a storage profile: `%memit` and `%mprun`\n", "\n", - "Ein weiterer Aspekt der Profilerstellung ist die Speichermenge, die eine Operation verwendet. Dies kann mit einer anderen IPython-Erweiterung ausgewertet werden, dem `memory_profiler`. Diese kann in eurem Kernel bereitgestellt werden mit\n", + "Another aspect of profiling is the amount of memory that an operation uses. This can be evaluated with another IPython extension, the `memory_profiler`. This can be provided in your kernel with\n", "\n", "```\n", "$ spack env activate python-374\n", "$ spack install py-memory-profiler ^python@3.7.4%gcc@9.1.0\n", "```\n", "\n", - "Alternativ könnt ihr `memory-profiler` auch mit anderen Paketmanagern installieren, z.B.\n", + "Alternatively you can install `memory-profiler` with other package managers, e.g.\n", "\n", "```\n", "$ pipenv install memory_profiler\n", @@ -370,9 +371,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Wir sehen, dass diese Funktion ungefähr 100 MB Speicher belegt.\n", + "We see that this feature occupies approximately 100 MB of memory.\n", "\n", - "Für eine zeilenweise Beschreibung der Speichernutzung können wir die `%mprun`-Magie verwenden. Leider funktioniert diese Magie nur für Funktionen, die in separaten Modulen definiert sind, und nicht für das Notebook selbst. Daher erstellen wir zunächst mit der `%%file`-Magie ein einfaches Modul mit dem Namen `mprun_demo.py`, das unsere `sum_of_lists`-Funktion enthält." + "For a line-by-line description of memory usage, we can use the `%mprun` magic. Unfortunately, this magic only works for functions that are defined in separate modules and not for the notebook itself. So we first use the `%%file` magic to create a simple module called `mprun_demo.py` that contains our `sum_of_lists` function." ] }, { @@ -434,9 +435,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Hier zeigt die `Increment`-Spalte, wie stark sich jede Zeile auf den gesamten Speicherverbrauch auswirkt: Beachtet, dass wir beim Berechnen von `b` etwa 160 MB Speicher zusätzlich benötigen; dieser wird aber durch das Löschen von `b` nicht wieder freigegeben.\n", + "Here the `Increment` column shows how much each row affects the total memory consumption: Note that when we calculate `b` we need about 160 MB of additional memory; however, this is not released again by deleting `b`.\n", "\n", - "Weitere Informationen zu `%memit` und `%mprun` sowie deren Optionen findet ihr in der IPython-Hilfe mit `%memit?`." + "More information about `%memit`, `%mprun` and their options can be found in the IPython help with `%memit?`." ] }, { @@ -445,9 +446,9 @@ "source": [ "## pyheatmagic\n", "\n", - "[pyheatmagic](https://github.com/csurfer/pyheatmagic) ist eine Erweiterung, die den IPython-Magic-Befehl `%%heat` zum Anzeigen von Python-Code als Heatmap mit [Py-Heat](https://github.com/csurfer/pyheat) erlaubt.\n", + "[pyheatmagic](https://github.com/csurfer/pyheatmagic) is an extension that allows the IPython magic command `%%heat` to display Python code as a heatmap with [Py-Heat](https://github.com/csurfer/pyheat).\n", "\n", - "Sie lässt sich einfach im Kernel installieren mit\n", + "It can be easily installed in the kernel with\n", "\n", "```\n", "$ pipenv install py-heat-magic\n", @@ -459,7 +460,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Laden der Extension in IPython" + "### Loading the extension in IPython" ] }, { @@ -475,7 +476,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Anzeigen der Heatmap" + "### Display the heat map" ] }, { @@ -536,7 +537,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Alternativ kann die Heatmap auch als Datei gespeichert werden, z.B. mit\n", + "Alternatively, the heatmap can also be saved as a file, e.g. with\n", + "\n", "```\n", "%%heat -o pow-heatmap.png\n", "```" diff --git a/docs/workspace/ipython/shell.ipynb b/docs/workspace/ipython/shell.ipynb index d52f6921..bff4458f 100644 --- a/docs/workspace/ipython/shell.ipynb +++ b/docs/workspace/ipython/shell.ipynb @@ -4,14 +4,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Shell-Befehle in IPython" + "# Shell commands in IPython" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "z.B.:" + "e.g .:" ] }, { @@ -69,7 +69,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Werte an und von der Shell übergeben" + "## Passing values to and from the shell" ] }, { @@ -128,7 +128,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Shell-bezogene Magic-Befehle" + "## Shell-related magic commands" ] }, { @@ -203,9 +203,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## `%automagic`-Funktion\n", + "## `%automagic` function\n", "\n", - "Mit der `%automagic`-Funktion lassen sich diese auch ohne vorangestelltes `%`-Zeichen verwenden:" + "With the `%automagic` function, these can also be used without the preceding `%` character:" ] }, { diff --git a/docs/workspace/ipython/start.rst b/docs/workspace/ipython/start.rst index 7620dfd3..3ec454fa 100644 --- a/docs/workspace/ipython/start.rst +++ b/docs/workspace/ipython/start.rst @@ -1,7 +1,7 @@ -Starten der IPython-Shell -========================= +Start the IPython shell +======================= -Ihr könnt IPython einfach in einer Konsole starten: +You can easily start IPython in a console: .. code-block:: console @@ -12,8 +12,8 @@ Ihr könnt IPython einfach in einer Konsole starten: In [1]: -Alternativ könnt ihr IPython auch in einem Jupyter-Notebook verwenden. Hierfür -startet ihr zunächst den Notebook-Server: +Alternatively, you can use IPython in a Jupyter notebook. To do this, start the +notebook server first: .. code-block:: console @@ -24,8 +24,7 @@ startet ihr zunächst den Notebook-Server: [I 17:35:02.428 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). [C 17:35:02.497 NotebookApp] -Anschließend sollte der Standardbrowser mit der angegebenen URL geöffnet -werden. Häufig ist dies ``http://localhost:8888``. +The standard browser should then be opened with the specified URL. Often this is +``http://localhost:8888``. -Nun könnt ihr im Browser einen Python-Prozess starten, indem ihr ein neues -Notebook erstellt. +Now you can start a Python process in the browser by creating a new notebook. diff --git a/docs/workspace/jupyter/hub/config.rst b/docs/workspace/jupyter/hub/config.rst index a00fc452..c3ee5835 100644 --- a/docs/workspace/jupyter/hub/config.rst +++ b/docs/workspace/jupyter/hub/config.rst @@ -1,7 +1,7 @@ -Konfiguration +Configuration ============= -JupyterHub-Konfiguration +JupyterHub configuration ------------------------ .. code-block:: console @@ -14,10 +14,10 @@ JupyterHub-Konfiguration * :doc:`JupyterHub Configuration Basics ` * :doc:`JupyterHub Networking basics ` -System-Service für JupyterHub +System service for JupyterHub ----------------------------- -#. Ermitteln des *Python Virtual Environment*: +#. Finding the Python virtual environment: .. code-block:: console @@ -25,7 +25,7 @@ System-Service für JupyterHub $ pipenv --venv /srv/jupyter/.local/share/virtualenvs/jupyterhub-aFv4x91W -#. Konfigurieren von ``/etc/systemd/system/jupyterhub.service`` und +#. Configuring ``/etc/systemd/system/jupyterhub.service`` and ``/lib/systemd/system/jupyterhub.service``: .. code-block:: ini @@ -41,47 +41,45 @@ System-Service für JupyterHub [Install] WantedBy=multi-user.target -#. Laden der Konfiguration +#. Loading the configuration - mit: + with: .. code-block:: console # systemctl daemon-reload -#. Der JupyterHub lässt sich verwalten mit: +#. The JupyterHub can be managed with: .. code-block:: console # systemctl jupyterhub -#. Um sicherzustellen, dass der Dienst auch bei einem Systemstart mitgeladen - wird, wird folgendes aufgerufen: +#. To ensure that the service is also loaded when the system is started, the + following is called: .. code-block:: console $ systemctl enable jupyterhub.service systemctl enable jupyterhub.service -TLS-Verschlüsselung -------------------- +TLS encryption +-------------- -Da JupyterHub eine Authentifizierung beinhaltet und die Ausführung von -beliebigem Code erlaubt, sollte es nicht ohne SSL (HTTPS) ausgeführt werden. -Dazu muss ein offizielles, vertrauenswürdiges SSL-Zertifikat erstellt werden. -Nachdem ihr einen Schlüssel und ein Zertifikat erhalten und installiert habt, -konfiguriert ihr jedoch nicht das JupyterHub selbst sondern den vorgeschalteten -Apache Webserver. +Since JupyterHub includes authentication and allows the execution of any code, +it should not be executed without SSL (HTTPS). To do this, an official, +trustworthy SSL certificate must be created. After you have received and +installed a key and a certificate, you don’t configure the JupyterHub itself, +but the upstream Apache web server. -#. Hierfür werden zunächst die Zusatzmodule aktiviert mit +#. For this purpose, the additional modules are first activated with .. code-block:: apacheconf # a2enmod ssl rewrite proxy proxy_http proxy_wstunnel -#. Anschließend kann der VirtualHost in - ``/etc/apache2/sites-available/jupyter.cusy.io.conf`` konfiguriert - werden mit +#. Then the VirtualHost can be configured in + ``/etc/apache2/sites-available/jupyter.cusy.io.conf`` .. code-block:: console @@ -125,13 +123,13 @@ Apache Webserver. CustomLog ${APACHE_LOG_DIR}/jupyter.cusy.io_access.log combined -#. Dieser VirtualHost wird aktiviert mit +#. This VirtualHost is activated with .. code-block:: console # a2ensite jupyter.cusy.io.conf -#. Schließlich wird der Status des Apache-Webserver überprüft mit +#. Finally, the status of the Apache web server is checked with .. code-block:: console @@ -149,25 +147,25 @@ Apache Webserver. Mar 27 06:25:01 jupyter.cusy.io systemd[1]: Reloaded The Apache HTTP Server. -Cookie-Secret +Cookie Secret ------------- -Das Cookie secret ist zum Verschlüsseln der Browser-Cookies, die zur -Authentifizierung verwendet werden. +The cookie secret is used to encrypt the browser cookies that are used for +authentication. -#. Das Cookie-Secret kann z.B. erstellt werden mit +#. The cookie secret can e.g. be created with .. code-block:: console $ openssl rand -hex 32 > /srv/jupyterhub/venv/jupyterhub_cookie_secret -#. Die Datei sollte weder für ``group`` noch für ``anonymous`` lesbar sein: +#. The file should not be readable by either ``group`` or ``anonymous``: .. code-block:: console $ chmod 600 /srv/jupyterhub/venv/jupyterhub_cookie_secret -#. Schließlich wird es in die ``jupyterhub_config.py``-Datei eingetragen: +#. Finally it will be entered in the ``jupyterhub_config.py`` file: .. code-block:: python @@ -176,20 +174,18 @@ Authentifizierung verwendet werden. Proxy authentication token -------------------------- -Der Hub authentifiziert seine Anforderungen an den Proxy unter Verwendung -eines geheimen Tokens, auf das sich der Hub und der Proxy einigen. -Üblicherweise muss der Proxy authentication token nicht festgelegt werden, -da der Hub selbst einen zufälligen Schlüssel generiert. Dies bedeutet, dass -der Proxy jedes Mal neu gestartet werden muss sofern der Proxy nicht ein -Unterprozess des Hubs ist. +The hub authenticates its requests to the proxy using a secret token that the +hub and proxy agree on. Usually, the proxy authentication token does not need to +be set, as the hub itself generates a random key. This means that the proxy has +to be restarted every time unless the proxy is a subprocess of the hub. -#. Alternativ kann Der Wert z.B. generiert werden mit +#. Alternatively, the value can e.g. can be generated with .. code-block:: console $ openssl rand -hex 32 -#. Anschließend kann er in der Konfigurationsdatei eingetragen werde, z.B. mit +#. It can then be entered in the configuration file, e.g. with .. code-block:: python diff --git a/docs/workspace/jupyter/hub/index.rst b/docs/workspace/jupyter/hub/index.rst index 45ecf5d2..4ccfc858 100644 --- a/docs/workspace/jupyter/hub/index.rst +++ b/docs/workspace/jupyter/hub/index.rst @@ -1,10 +1,9 @@ JupyterHub ========== -`JupyterHub `_ ist ein Multi-User Server für -:doc:`Jupyter Notebooks `, der viele -verschiedene Instanzen von Jupyter Notebooks erzeugen und verwalten kann und der -als Proxy fungiert. +`JupyterHub `_ is a multi-user server for +Jupyter Notebooks, which can create and manage many different instances of +Jupyter Notebooks and which acts as a proxy. .. toctree:: :hidden: diff --git a/docs/workspace/jupyter/hub/install.rst b/docs/workspace/jupyter/hub/install.rst index 4664a146..c7610081 100644 --- a/docs/workspace/jupyter/hub/install.rst +++ b/docs/workspace/jupyter/hub/install.rst @@ -1,7 +1,7 @@ Installation ============ -#. Python≥3.5 und pip installieren: +#. Install Python≥3.5 and pip: .. code-block:: console @@ -11,55 +11,55 @@ Installation Python 3.7.3 # apt install python3-pip -#. Service-User ``jupyter`` erstellen: +#. Create service user ``jupyter``: .. code-block:: console # useradd -s /bin/bash -rmd /srv/jupyter jupyter -#. Als Service-User ``jupyter`` das Repository klonen: +#. Clone the repository as service user ``jupyter``: .. code-block:: console # su - jupyter $ git clone https://github.com/veit/jupyter-tutorial.git -#. `Pipenv `_ installieren: +#. Install `Pipenv `_: .. code-block:: console $ python3 -m pip install --user pipenv - Dies installiert Pipenv in ``USER_BASE``. + This installs Pipenv in ``USER_BASE``. -#. ``USER_BASE`` ermitteln und in ``PATH`` eintragen: +#. Determine ``USER_BASE`` and enter it in ``PATH``: .. code-block:: console $ python3 -m site --user-base /srv/jupyter/.local - Anschließend muss noch das ``bin``-Verzeichnis angehängt und zu ``PATH`` - in ``~/.profile`` hinzugefügt werden, also: + Then the ``bin`` directory has to be appended and added to + ``PATH``, so: .. code-block:: console export PATH=/srv/jupyter/.local/bin:$PATH - Schließlich wird das geänderte Profil eingelesen mit: + Finally the changed profile is read in with: .. code-block:: console $ source ~/.profile -#. Virtuelle Umgebung erstellen und JupyterHub installieren: +#. Create a virtual environment and install JupyterHub: .. code-block:: console $ cd jupyter-tutorial/ $ pipenv install -#. ``nodejs`` und ``npm`` installieren: +#. Install ``nodejs`` and ``npm``: .. code-block:: console @@ -73,15 +73,15 @@ Installation # npm -v 6.10.2 - ``10.x`` gibt dabei die Major-Version von ``nodejs`` an. + ``10.x`` indicates the major version of ``nodejs``. -#. Installieren der ``npm``-Pakete: +#. Installi the ``npm`` packages: .. code-block:: console $ npm install -#. Installieren des HTTP-Proxy: +#. Install the HTTP-Proxy: .. code-block:: console @@ -90,7 +90,7 @@ Installation + configurable-http-proxy@4.1.0 added 47 packages from 62 contributors in 6.208s -#. Testen der Installation: +#. Testing the installation: .. code-block:: console @@ -98,4 +98,4 @@ Installation … [I 2019-07-31 22:47:26.617 JupyterHub app:1912] JupyterHub is now running at http://:8000 - Mit ctrl-c könnt ihr den Prozess wieder beenden. + With ``ctrl-c`` you can end the process again. diff --git a/docs/workspace/jupyter/hub/nbviewer-service.rst b/docs/workspace/jupyter/hub/nbviewer-service.rst index 67d7dcd9..63e2f295 100644 --- a/docs/workspace/jupyter/hub/nbviewer-service.rst +++ b/docs/workspace/jupyter/hub/nbviewer-service.rst @@ -1,11 +1,12 @@ -Service ``nbviewer`` erstellen -============================== +Create service ``nbviewer`` +=========================== -#. Die Konfigurieren des Notebook-Viewer als JupyterHub-Service hat den - Vorteil, dass nur Benutzer, die sich zuvor beim JupyterHub angemeldet haben, - die ``nbviewer``-Instanz aufrufen können. Damit kann der Zugriff auf - Notebooks geschützt werden, als JupyterHub-Service in - ``/srv/jupyter/jupyter-tutorial/jupyterhub_config.py``:: +#. Configuring the notebook viewer as a JupyterHub service has the advantage + that only users who have previously logged on to JupyterHub can call up the + ``nbviewer`` instance. This can be used to protect access to notebooks as a + JupyterHub service in ``/srv/jupyter/jupyter-tutorial/jupyterhub_config.py``: + + .. code-block:: javascript c.JupyterHub.services = [ { @@ -17,10 +18,10 @@ Service ``nbviewer`` erstellen ] ``name`` - Der Pfadname unter dem der Notebook-Viewer erreichbar ist: ``/services/`` + The path name under which the notebook viewer can be reached:: ``/services/`` ``url`` - Protokoll, Adresse und Port, die ``nbviewer`` verwendet + Protocol, address and port used by ``nbviewer`` ``cwd`` - Der Pfad zum ``nbviewer``-Repository + The path to the ``nbviewer`` repository ``command`` - Kommando um ``nbviewer`` zu starten + Command to start ``nbviewer`` diff --git a/docs/workspace/jupyter/index.rst b/docs/workspace/jupyter/index.rst index 5dff68f4..e835a4a9 100644 --- a/docs/workspace/jupyter/index.rst +++ b/docs/workspace/jupyter/index.rst @@ -7,93 +7,93 @@ Jupyter graph [fontname = "Calibri", fontsize="16"]; node [fontname = "Calibri", fontsize="16"]; edge [fontname = "Calibri", fontsize="16"]; - tooltip="Wie entscheide ich, welche Jupyter-Pakete ich benötige?"; + tooltip="How do I decide which Jupyter packages I need?"; // Top Level what [ shape=diamond, - label="Was wollt ihr machen?", - tooltip="Jupyter bietet euch verschiedene Möglichkeiten, wie ihr die Notebooks nutzen könnt"] + label="What do you want to do?", + tooltip="Jupyter offers you different ways how you can use the notebooks"] // Second Level jupyter [ label="Jupyter", - tooltip="Jupyter lokal installieren", + tooltip="Install Jupyter locally", target="_top", href="../workspace/jupyter/notebook/index.html"] hub [ label="JupyterHub", - tooltip="JupyterHub\ninstallieren", + tooltip="Install\nJupyterHub", target="_top", href="../workspace/jupyter/hub/index.html"] nbconvert [ label="nbconvert", - tooltip="nbconvert installieren und nutzen", + tooltip="Install and\nuse nbconvert", target="_top", href="../workspace/jupyter/nbconvert.html"] nbviewer [ label="nbviewer", - tooltip="nbviewer installieren und nutzen", + tooltip="Install and\nuse nbviewer", target="_top", href="../workspace/jupyter/nbviewer.html"] kernels [ label="Kernels", - tooltip="Kernels installieren, anzeigen und starten", + tooltip="Install, view and\nstart kernels", target="_top", href="../workspace/jupyter/kernels/install.html"] extensions [ shape=plaintext, label=" ", - tooltip="Notebook-Erweiterungen installieren"] + tooltip="Install notebook extensions"] embed [ shape=plaintext, label="", - tooltip="Notebooks in andere Anwendungen einbinden"] + tooltip="Embed notebooks in other applications"] examples [ - label="Unternehmens-\nanwendungen", - tooltip="Anwendungsbeispiele bei Netflix, Bloomberg etc.", + label="Enterprise\napplications", + tooltip="Application examples at\nNetflix, Bloomberg etc.", target="_top", href="../workspace/jupyter/use-cases.html"] // 3rd Level widgets [ label="Widgets", - tooltip="ipywidgets installieren und nutzen", + tooltip="Install and\nuse ipywidgets", target="_top", href="../workspace/jupyter/ipywidgets/index.html"] extend [ label="nbextensions", - tooltip="Installieren und Verwenden verschiedener Notebook-Erweiterungen", + tooltip="Install and use various\nnotebook extensions", target="_top", href="../workspace/jupyter/nbextensions/index.html"] viz [ - label="Visualisierung", - tooltip="Bibliotheken zur Datenvisualisierung", + label="Visualisation", + tooltip="Data visualisation libraries", target="_top", href="../viz/index.html"] dash [ label="Dashboards", - tooltip="Installieren und Verwenden von Dashboards", + tooltip="Install and\nuse Dashboards", target="_top", href="../web/dashboards/index.html"] html [ label="HTML", - tooltip="Einbinden von Notebooks in statisches HTML", + tooltip="Embed notebooks in\nstatic HTML", target="_top", href="../workspace/jupyter/ipywidgets/embedding.html"] sphinx [ label="Sphinx", - tooltip="Einbinden von Notebooks in den Sphinx Document Generator", + tooltip="Embed notebooks in the\nSphinx Document Generator", target="_top", href="../workspace/jupyter/nbsphinx.html"] // Edges - what -> jupyter [label="Einzel-\nnutzer"] - what -> hub [label="Team-\narbeit"] - what -> nbconvert [label="Konvertieren"] - nbconvert -> nbviewer [label="Konvertier-\nservice"] + what -> jupyter [label="Single\nuser"] + what -> hub [label="Teamwork"] + what -> nbconvert [label="Convert"] + nbconvert -> nbviewer [label="Conversion\nservice"] what -> kernels [label="Java, R,\nJulia etc."] - what -> extensions [label="Notebook\nerweitern"] - what -> embed [label="Notebooks\neinbetten"] - what -> examples [label="Beispiele"] + what -> extensions [label="Extend\nNotebook"] + what -> embed [label="Embed\nNotebooks"] + what -> examples [label="Examples"] extensions -> {widgets extend viz dash} - embed -> {html sphinx} + embed -> {html sphinx} [label="Embed"] // Arrangement {rank = same; what;} {rank = same; jupyter; hub; nbconvert; kernels; extensions; embed; examples;} diff --git a/docs/workspace/jupyter/ipywidgets/custom-widget.ipynb b/docs/workspace/jupyter/ipywidgets/custom-widget.ipynb index 5628e70e..be2a6c8d 100644 --- a/docs/workspace/jupyter/ipywidgets/custom-widget.ipynb +++ b/docs/workspace/jupyter/ipywidgets/custom-widget.ipynb @@ -4,23 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Benutzerdefiniertes Widget" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Das Widget-Framework basiert auf dem [Comms](https://jupyter-notebook.readthedocs.io/en/stable/comms.html)-Framework, das dem Kernel ermöglicht, JSON an das Frontend zu senden und zu empfangen. Um nun ein benutzerdefiniertes Widget zu erstellen, muss das Widget sowohl im Browser als auch im Python-Kernel definiert werden.\n", + "# Custom widget\n", + "\n", + "The widget framework is based on the [Comms](https://jupyter-notebook.readthedocs.io/en/stable/comms.html) framework, which enables the kernel to send and receive JSON to the front end. In order to create a custom widget, the widget must be defined both in the browser and in the Python kernel.\n", "\n", - "Weitere Informationen zum Comms-Framework erhaltet ihr im [Low Level Widget Tutorial](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Low%20Level.html)." + "For more information on the Comms framework, see the [Low Level Widget Tutorial](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Low%20Level.html)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Python-Kernel" + "## Python kernel" ] }, { @@ -29,7 +24,7 @@ "source": [ "### DOMWidget\n", "\n", - "Um ein Widget zu definieren, muss es von der Basisklasse `Widget` oder `DOMWidget` erben. Wenn das Widget im Jupyter-Notebook angezeigt werden soll, sollte euer Widget von `DOMWidget` erben. Dabei erbt Die `DOMWidget`-Klasse selbst von der `Widget`-Klasse. " + "To define a widget, it must inherit from the `Widget` or `DOMWidget` base class. If the widget is to be displayed in the Jupyter notebook, your widget should inherit from `DOMWidget`. The `DOMWidget` class itself inherits from the `Widget` class." ] }, { @@ -38,15 +33,15 @@ "source": [ "### `_view_name`\n", "\n", - "Durch die Übernahme von `DOMWidget` wird dem Widget-Framework **nicht** mitgeteilt, welches Frontend-Widget mit dem Backend-Widget verknüpft werden soll.\n", + "By adopting `DOMWidget`, the widget framework is **not** informed which front-end widget should be linked to the back-end widget.\n", "\n", - "Stattdessen müsst ihr dies selbst angeben durch eines der folgenden Attribute:\n", + "Instead, you have to specify this yourself using one of the following attributes:\n", "\n", "* `_view_name`\n", "* `_view_module`\n", "* `_view_module_version`\n", "\n", - "und gegebenenfalls\n", + "and if applicable\n", "\n", "* `_model_name`\n", "* `_model_module`" @@ -73,7 +68,7 @@ "source": [ "### `sync=True`-Traitlets\n", "\n", - "[Traitlets](https://traitlets.readthedocs.io/en/stable/) ist ein Framework, mit dem Python-Klassen Attribute mit Typprüfung, dynamisch berechneten Standardwerten und Callbacks bei Änderung haben können. Das `sync=True`- Keyword-Argument weist das Widget-Framework an, den Wert mit dem Browser zu synchronisieren; ohne würde der Browser nichts von `_view_name` oder `_view_module` erfahren." + "[Traitlets](https://traitlets.readthedocs.io/en/stable/) is a framework with which Python classes can have attributes with type checking, dynamically calculated default values and callbacks when changed. The `sync=True` keyword argument tells the widget framework to synchronise the value with the browser; without it, the browser would not learn anything about `_view_name` or `_view_module`." ] }, { @@ -87,18 +82,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### *Models* und *Views*\n", + "### Models and Views\n", "\n", - "Das Frontend des IPython-Widget-Frameworks hängt stark von [Backbone.js](http://backbonejs.org/) ab. *Backbone.js* ist ein MVC-Framework ([Model View Controller](https://de.wikipedia.org/wiki/Model_View_Controller)), das im Backend definierte Widgets automatisch mit generischen *Backbone.js*-Modellen im Frontend synchronisiert: das vorher definierte `_view_name`-Merkmal wird vom Widget-Framework verwendet, um die entsprechende *Backbone.js*-*View* zu erstellen und diese mit dem *Model* zu verknüpfen." + "The front end of the IPython widget framework depends heavily on [Backbone.js](http://backbonejs.org/). Backbone.js is an [Model View Controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (MVC) framework that automatically synchronises widgets defined in the backend with generic Backbone.js models in the frontend: the previously defined `_view_name` characteristic is used by the widget framework to display the corresponding Backbone.js-View and link it to the model." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### `@jupyter-widgets/base` importieren\n", + "### Import `@jupyter-widgets/base`\n", "\n", - "Ihr müsst zuerst das `@jupyter-widgets/base`-Modul mit der `define`-Methode von [RequireJS](https://requirejs.org/)." + "First you have to use the `@jupyter-widgets/base` module with the `define` method of [RequireJS](https://requirejs.org/)." ] }, { @@ -132,9 +127,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### View definieren\n", + "### Define view\n", "\n", - "Als nächstes definieren wir die Widget-*View*-Klasse wobei wir von `DOMWidgetView` mit der `.extend`-Methode erben." + "Next we define the widget view class and we inherit from `DOMWidgetView` with the `.extend` method." ] }, { @@ -182,9 +177,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### `render`-Methode\n", + "### `render` method\n", "\n", - "Zum Schluss müssen wir noch die Basismethode `render` überschreiben um eine benutzerdefinierte Rendering-Logik zu definieren. Ein Handle auf das Standard-DOM-Element des Widgets kann mit `this.el` aufgerufen werden. Die `el`-Eigenschaft ist das DOM-Element, das der Ansicht zugeordnet ist." + "Finally, we still have to override the basic `render` method to define a custom rendering logic. A handle to the standard DOM element of the widget can be called with `this.el`. The `el` property is the DOM element associated with the view." ] }, { @@ -240,7 +235,7 @@ "source": [ "## Test\n", "\n", - "Das Widget lässt sich jetzt wie jedes andere Widget anzeigen mit" + "The widget can now be displayed like any other widget with" ] }, { @@ -271,18 +266,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## *Stateful* Widget\n", + "## Stateful widget\n", "\n", - "Mit dem obigen Beispiel könnt ihr noch nicht viel tun. Um dies zu ändern, müsst ihr das Widget *stateful* machen. Anstelle einer statischen *Hello World!*-Meldung soll eine vom Backend festgelegter *String* angezeigt werden. Hierzu wird zunächst ein neues Traitlet hinzugefügt. Verwendet hierbei den Namen von `value`, um mit dem Rest des Widget-Frameworks konsistent zu bleiben und die Verwendung eures Widgets mit Interaktion zu ermöglichen." + "There’s not much you can do with the example above. To change this, you have to make the widget stateful. Instead of a static Hello World! Message, a string specified by the backend should be displayed. To do this, a new traitlet is first added. Use the name of `value` here to stay consistent with the rest of the widget framework and to allow your widget to be used with interaction." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Jupyter Widgets aus einem Template erstellen\n", + "## Create Jupyter widgets from a template\n", "\n", - "Mit [widget-cookiecutter](https://github.com/jupyter/widget-cookiecutter) ist ein [Cookiecutter](https://github.com/audreyr/cookiecutter)-Template verfügbar. Es enthält eine Implementierung für ein Platzhalter-Widget *Hello World*. Darüberhinaus erleichtert es euch das Packen und Verteilen eurer Jupyter Widgets." + "A [Cookiecutter](https://github.com/cookiecutter/cookiecutter) is available with [widget-cookiecutter](https://github.com/jupyter/widget-cookiecutter). It contains an implementation for a placeholder widget *Hello World*. It also makes it easier for you to pack and distribute your Jupyter widgets." ] } ], diff --git a/docs/workspace/jupyter/ipywidgets/embedding.rst b/docs/workspace/jupyter/ipywidgets/embedding.rst index bff715a2..824fff84 100644 --- a/docs/workspace/jupyter/ipywidgets/embedding.rst +++ b/docs/workspace/jupyter/ipywidgets/embedding.rst @@ -1,73 +1,71 @@ -Einbetten von Jupyter-Widgets -============================= +Embed Jupyter widgets +===================== -Jupyter-Widgets können serialisiert und dann in andere Kontexte eingebettet -werden: +Jupyter widgets can be serialised and then embedded in other contexts: -* statische Webseiten -* Sphinx-Dokumentation -* HTML-konvertierte Notebooks auf Nbviewer +* static web pages +* Sphinx documentation +* HTML converted notebooks on Nbviewer -Dabei erlaubt das npm-Paket ``@jupyter-widgets/html-manager`` das Einbetten auf -zwei unterschiedliche Weisen: -* das Einbetten der Standardelemente, die auf jeder Website verwendet werden - können -* das Einbetten mit `RequireJS `_ auch für - benutzerdefinierte Widgets. +The npm package ``@jupyter-widgets/html-manager`` allows embedding in two +different ways: -Einbetten von Widgets in HTML-Seiten ------------------------------------- -Hierfür stellt das *Widgets*-Menü mehrere Optionen zur Verfügung: +* embedding the standard elements that can be used on any website +* embedding with `RequireJS `_ also for custom widgets. + +Embed widgets in HTML pages +--------------------------- + +The widgets menu provides several options for this: *Save Notebook Widget State* - Eine Notebook-Datei wird mit dem aktuellen Widget-Status als Metadaten - gespeichert. Dadurch kann sie mit den Widgets im Browser gerendert werden. + A notebook file is saved with the current widget status as metadata. This + allows to be rendered with the widgets in the browser. *Clear Notebook Widget State* - Die Metadaten des Widget-Status werden aus der Notebook-Datei gelöscht. + The widget status metadata is deleted from the notebook file. *Embed widgets* - Der Menüpunkt bietet ein Dialogfeld mit einer HTML-Seite, auf der die - aktuellen Widgets eingebettet sind. Um benutzerdefinierte Widgets zu - unterstützen, wird der RequireJS-Embedder verwendet. + The menu item offers a dialog box with an HTML page on which the current + widgets are embedded. The RequireJS embedder is used to support custom + widgets. .. note:: - Das erste Skript-Tag lädt RequireJS von einem CDN. RequireJS sollte - jedoch auf der Site selbst zur Verfügung gestellt und dieser Skript-Tag - gelöscht werden. + The first script tag loads RequireJS from a CDN. However, RequireJS + should be made available on the site itself and this script tag should + be deleted. .. note:: - Das zweite Skript-Tag lädt den RequireJS-Widget-Embedder. Dadurch werden - geeignete Module definiert und anschließend eine Funktion zum Rendern - aller auf der Seite enthaltenen Widget-Ansichten eingerichtet. + The second script tag loads the RequireJS widget embedder. This defines + suitable modules and then sets up a function for rendering all widget + views contained on the page. - Wenn ihr nur Standard-Widgets einbettet und RequireJS nicht verwendet, - könnt ihr die ersten beiden Skript-Tags durch ein Skript-Tag ersetzen, - das das Standard-Skript lädt. + If you only embed standard widgets and don’t use RequireJS, you can + replace the first two script tags with a script tag that loads the + standard script. *Download Widget State* - Die Option lädt eine JSON-Datei herunter, die den serialisierten Status - aller derzeit verwendeten Widget-Modelle im Format - ``application/vnd.jupyter.widget-state+json`` enthält, das im npm-Paket - ``@jupyter-widgets/schema`` spezifiziert ist. + The option downloads a JSON file that contains the serialized status of all + widget models currently in use in the + ``application/vnd.jupyter.widget-state+json`` format specified in the + ``@jupyter-widgets/schema`` npm package. -Sphinx-Integration +Sphinx integration ------------------ Jupyter Sphinx ~~~~~~~~~~~~~~ -`jupyter_sphinx `_ ermöglicht -jupyter-spezifische Funktionen in Sphinx. Es kann mit ``pip`` installiert -werden. +`jupyter_sphinx `_ enables +jupyter-specific functions in Sphinx. It can be installed with ``pip``. -Konfiguration +Configuration ::::::::::::: -Fügt in der ``conf.py``-Datei ``jupyter_sphinx.embed_widgets`` in der Liste der -Erweiterungen hinzu. +Adds ``jupyter_sphinx.embed_widgets`` to the list of extensions in the +``conf.py`` file. -Anschließend könnt ihr in reStructuredText folgende Direktiven verwenden: +Then you can use the following directives in reStructuredText: ``ipywidgets-setup`` :: @@ -83,8 +81,8 @@ Anschließend könnt ihr in reStructuredText folgende Direktiven verwenden: VBox([s1, s2, b]) -Beispiel -:::::::: +Example +::::::: :: @@ -100,23 +98,24 @@ Beispiel jsdlink((s1, 'value'), (s2, 'max')) VBox([s1, s2, b]) -Optionen -:::::::: +Options +::::::: -Die Direktiven ``ipywidgets-setup`` und ``ipywidgets-display`` haben die -folgenden Optionen: +The ``ipywidgets-setup`` and ``ipywidgets-display`` directives have the +following options: ``ipywidgets-setup`` - mit der Option ``:show:`` um den Setup-Code als Code-Block darzustellen + with the option ``:show:`` to display the setup code as a code block ``ipywidgets-display`` - mit den folgenden Optionen: + with the following options: ``:hide-code:`` - zeigt den Code nicht an sondern nur das Widget + doesn’t show the code, only the widget + Widget ``:code-below:`` - zeigt den Code nach dem Widget an + shows the code after the widget ``:alt:`` - Alternativer Text, wenn das Widget nicht gerendert werden kann + Alternate text if the widget cannot be rendered .. seealso:: `Options `_ diff --git a/docs/workspace/jupyter/ipywidgets/examples.ipynb b/docs/workspace/jupyter/ipywidgets/examples.ipynb index 2a7fad82..bd2d430b 100644 --- a/docs/workspace/jupyter/ipywidgets/examples.ipynb +++ b/docs/workspace/jupyter/ipywidgets/examples.ipynb @@ -4,22 +4,23 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Beispiele" + "# Examples" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "IPython enthält eine Architektur für interaktive Widgets, die Python-Code, der im Kernel ausgeführt wird, und JavaScript/HTML/CSS, die im Browser ausgeführt werden, zusammenfügt. Mit diesen Widgets können Benutzer ihren Code und ihre Daten interaktiv untersuchen." + "IPython includes an interactive widget architecture that combines Python code running in the kernel and JavaScript/HTML/CSS running in the browser. These widgets allow users to interactively examine their code and data." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Interact-Funktion\n", - "`ipywidgets.interact` erstellt automatisch User-Interface(UI)-Controls, um Code und Daten interaktiv zu erkunden." + "### Interact function\n", + "\n", + "`ipywidgets.interact` automatically creates user interface (UI) controls to interactively explore code and data." ] }, { @@ -37,7 +38,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Im einfachsten Fall generiert `interact` automatisch Steuerelemente für Funktionsargumente und ruft dann die Funktion mit diesen Argumenten auf, wenn Sie die Steuerelemente interaktiv bearbeiten. Im folgenden eine Funktion, die ihr einziges Argument `x` ausgibt." + "In the simplest case, `interact` automatically generates controls for function arguments and then calls the function with those arguments when you interactively edit the controls. The following is a function that returns its only argument `x`." ] }, { @@ -55,7 +56,9 @@ "metadata": {}, "source": [ "#### Slider\n", - "Wenn ihr eine Funktion mit einem ganzzahligen *keyword argument* (`x=10`) angebt, wird ein Schieberegler generiert und an den Funktionsparameter gebunden:" + "\n", + "\n", + "If you specify a function with an integer keyword argument (`x=10`), a slider is generated and bound to the function parameter:" ] }, { @@ -87,7 +90,8 @@ "metadata": {}, "source": [ "#### Checkbox\n", - "Wenn ihr `True` oder `False` angebt, generiert `interact` eine Checkbox:" + "\n", + "If you specify `True` or `False`, interact generates a checkbox:" ] }, { @@ -118,8 +122,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### Textbereich\n", - "Wenn ihr einen String übergebt, generiert `interact` einen Textbereich:" + "#### Text area\n", + "\n", + "If you pass a string, `interact` generates a text area:" ] }, { @@ -151,7 +156,8 @@ "metadata": {}, "source": [ "### Decorator\n", - "`interact` kann auch als Decorator verwendet werden. Auf diese Weise könnt ihr eine Funktion definieren und in einer einzigen Einstellung damit interagieren. Wie das folgende Beispiel zeigt, funktioniert `interact` auch mit Funktionen, die mehrere Argumente haben:" + "\n", + "`interact` can also be used as a decorator. This way you can define a function and interact with it in a single setting. As the following example shows, `interact` also works with functions that have multiple arguments:" ] }, { diff --git a/docs/workspace/jupyter/ipywidgets/index.rst b/docs/workspace/jupyter/ipywidgets/index.rst index 43cc24d6..94b1094e 100644 --- a/docs/workspace/jupyter/ipywidgets/index.rst +++ b/docs/workspace/jupyter/ipywidgets/index.rst @@ -1,10 +1,9 @@ ``ipywidgets`` ============== -`ipywidgets `_ sind interaktive Widgets für -Jupyter Notebooks. Sie erweitern Notebooks um die Möglichkeit, dass Nutzer -selbst Daten eingeben, Daten manipulieren und die veränderten Ergebnisse sehen -können. +`ipywidgets `_ are interactive widgets for +Jupyter notebooks. They extend notebooks by the possibility that users can enter +data themselves, manipulate data and see the changed results. .. toctree:: :hidden: diff --git a/docs/workspace/jupyter/ipywidgets/libs/index.rst b/docs/workspace/jupyter/ipywidgets/libs/index.rst index 8120a8fd..57d1bbf5 100644 --- a/docs/workspace/jupyter/ipywidgets/libs/index.rst +++ b/docs/workspace/jupyter/ipywidgets/libs/index.rst @@ -1,15 +1,15 @@ -ipywidgets-Bibliotheken -======================= +ipywidgets libraries +==================== -Beliebte Widget-Bibliotheken sind +Popular widget libraries are ``qplot`` - 2-D Plotting-Bibliothek für Jupyter-Notebooks + 2-D plotting library for Jupyter notebooks * :doc:`pyviz:d3js/bqplot/index` ``ipycanvas`` - Interaktive Canvas-Elemente in Jupyter-Notebooks + Interactive canvas elements in Jupyter notebooks .. toctree:: :maxdepth: 1 @@ -17,25 +17,25 @@ Beliebte Widget-Bibliotheken sind ipycanvas.ipynb ``pythreejs`` - Jupyter-`Three.js `_-Bridge + Jupyter `Three.js `_ bridge * :doc:`pyviz:js/pythreejs` ``ipyvolume`` - IPyvolume ist eine Python-Bibliothek zur Visualisierung von 3D-Volumen und - Glyphen (z.B. 3D-Scatter-Plots). + IPyvolume is a Python library for visualizing 3D volumes and glyphs (e.g. + 3D scatter plots). * :doc:`pyviz:js/ipyvolume` ``ipyleaflet`` - Jupyter-`Leaflet.js `_-Bridge + Jupyter-`Leaflet.js `_ bidge * :doc:`pyviz:js/ipyleaflet` ``ipywebrtc`` - `WebRTC `_- und `MediaStream-API - `_ für - Jupyter-Notebooks + `WebRTC `_ and `MediaStream + `_ API for + Jupyter notebooks .. toctree:: :maxdepth: 1 @@ -43,8 +43,7 @@ Beliebte Widget-Bibliotheken sind ipywebrtc.ipynb ``ipysheet`` - Interaktive Tabellen um IPython Widgets in Tabellen von Jupyter Notebooks - zu verwenden. + Interactive tables to use IPython widgets in tables of Jupyter notebooks. .. toctree:: :maxdepth: 1 @@ -52,8 +51,8 @@ Beliebte Widget-Bibliotheken sind ipysheet.ipynb ``qgrid`` - Widget auf Basis von `SlickGrid `_ - zum Rendern von pandas DataFrames in Jupyter-Notebooks + Widget based on `SlickGrid `_ for + rendering pandas DataFrames in Jupyter notebooks .. toctree:: :maxdepth: 1 @@ -61,7 +60,7 @@ Beliebte Widget-Bibliotheken sind qgrid.ipynb ``ipyvuetify`` - `Vuetify `_-Widgets in Jupyter Notebooks + `Vuetify `_ widgets in Jupyter notebooks .. toctree:: :maxdepth: 1 @@ -69,9 +68,9 @@ Beliebte Widget-Bibliotheken sind ipyvuetify.ipynb ``ipympl`` - ``ipympl`` oder `jupyter-matplotlib - `_ bieten interaktive - Widgets für Matplotlib. + ``ipympl`` or `jupyter-matplotlib + `_ offer interactive + widgets for matplotlib. .. toctree:: :maxdepth: 1 diff --git a/docs/workspace/jupyter/ipywidgets/libs/ipycanvas.ipynb b/docs/workspace/jupyter/ipywidgets/libs/ipycanvas.ipynb index 5f11e7bc..e05c4c71 100644 --- a/docs/workspace/jupyter/ipywidgets/libs/ipycanvas.ipynb +++ b/docs/workspace/jupyter/ipywidgets/libs/ipycanvas.ipynb @@ -6,10 +6,10 @@ "source": [ "# `ipycanvas`\n", "\n", - "stellt die [Web-Canvas-API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) zur Verfügung. Es gibt jedoch einige Unterschiede:\n", + "provides the [Web-Canvas-API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API). However, there are some differences:\n", "\n", - "* Das Canvas-Widget macht die [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D)-API direkt verfügbar\n", - "* Die gesamte API ist in `snake_case` anstatt in `camelCase` geschrieben, sodass beispielsweise das in Python geschriebene `canvas.fillStyle = 'red'` in JavaScript zu `canvas.fill_style = 'red'` wird." + "* The Canvas widget exposes the [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) API directly\n", + "* The entire API is written in `snake_case` instead of `camelCase`, so for example `canvas.fillStyle = 'red'` written in Python becomes `canvas.fill_style = 'red'` in JavaScript." ] }, { @@ -29,20 +29,20 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Erstellen von Canvas-Elementen\n", + "## Creating canvas elements\n", "\n", - "Bevor wir mit dem Erstellen von Canvas-Elementen beginnen können, zunächst ein Hinweis zum Canvas-Raster. Der Ursprung eines Gitters befindet sich in der oberen linken Ecke bei der Koordinate (0,0). Alle Elemente werden relativ zu diesem Ursprung platziert.\n", + "Before we can start creating canvas elements, first a note about the canvas grid. The origin of a grid is in the upper left corner at the coordinate `(0,0)`. All elements are placed relative to this origin.\n", "\n", - "Es gibt vier Methoden zum Zeichnen von Rechtecken:\n", + "There are four methods of drawing rectangles:\n", "\n", - "* `fill_rect(x, y, width, height=None)` zeichnet ein gefülltes Rechteck\n", - "* `stroke_rect(x, y, width, height=None)` zeichnet einen rechteckigen Umriss\n", - "* `fill_rects(x, y, width, height=None)` zeichnet gefüllte Rechtecke \n", - "* `stroke_rects(x, y, width, height=None)` zeichnet rechteckige Umrisse\n", + "* `fill_rect(x, y, width, height=None)` draws a filled rectangle\n", + "* `stroke_rect(x, y, width, height=None)` draws a rectangular outline\n", + "* `fill_rects(x, y, width, height=None)` draws filled rectangles\n", + "* `stroke_rects(x, y, width, height=None)` draws rectangular outlines\n", "\n", - "Mit `height=None` wird derselbe Wert verwendet wie bei `width`.\n", + "With `height=None`, the same value is used as with `width`.\n", "\n", - "Bei `*_rects` sind `x`, `y`, `width` und `height` ganze Zahlen, Listen von ganzen Zahlen oder Numpy-Arrays. " + "For `*_rects`, `x`, `y`, `width` and `height` are integers, lists of integers or numpy arrays." ] }, { @@ -161,18 +161,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> Da `Canvas` ein [ipywidget](https://ipywidgets.readthedocs.io/en/stable/) ist, kann es \n", - "> \n", - "> * mehrfach in einem Notebook vorkommen\n", - "> * die Attribute ändern\n", - "> * geänderte Attribute auf andere Widget-Attribute verlinken" + "Since `Canvas` is an [ipywidget](https://ipywidgets.readthedocs.io/en/stable/), it can\n", + "\n", + "* appear several times in a notebook\n", + "* change the attributes\n", + "* Link changed attributes to other widget attributes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Canvas löschen" + "## Delete canvas" ] }, { @@ -227,9 +227,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Formen\n", + "## Shapes\n", "\n", - "Die verfügbaren Zeichenkommandos sind:\n", + "The available drawing commands are:\n", "\n", "* `move_to(x, y)`: \n", "* `line_to(x, y)`: \n", @@ -244,16 +244,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Kreise zeichnen\n", + "### Draw circles\n", "\n", - "Es gibt vier verschiedene Arten, Kreise zu zeichnen:\n", + "There are four different ways to draw circles:\n", "\n", "* `fill_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)`\n", "* `stroke_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)`\n", "* `fill_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)`\n", "* `stroke_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)`\n", "\n", - "Bei `*_arcs` sind `x`, `y` und `radius` NumPy-Arrays, Listen oder skalare Werte." + "With `*_arcs`, `x`, `y` and `radius` are NumPy arrays, lists or scalar values." ] }, { @@ -296,14 +296,20 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Zeichenpfade\n", + "### Drawing paths\n", + "\n", + "A path is a list of points connected by line segments that can be different shapes, straight or curved, closed or open, different widths and colors. The following functions are available:\n", "\n", - "Ein Pfad ist eine Liste von Punkten, die durch Liniensegmente verbunden sind, die unterschiedliche Formen, gerade oder gekrümmt, geschlossen oder offen, unterschiedlich breit und farbig sein können. Dabei stehen die folgenden Funktionen zur Verfügung:\n", + " begin_path () \n", + " close_path () adds a straight line to the path leading to the beginning of the current path\n", + " stroke () draws the shape along the contour\n", + " fill (rule) draws the shape using a fill within the path\n", + " \n", "\n", - "* `begin_path()` erstellt einen neuen Pfad\n", - "* `close_path()` fügt dem Pfad eine gerade Linie hinzu, die zum Anfang des aktuellen Pfads führt\n", - "* `stroke()` zeichnet die Form entlang der Kontur\n", - "* `fill(rule)` zeichnet die Form durch eine Füllung innerhalb des Pfades" + "* `begin_path()` creates a new path\n", + "* `close_path()` adds a straight line to the path leading to the beginning of the current path\n", + "* `stroke()` draws the shape along the contour\n", + "* `fill(rule)` draws the shape using a fill within the path" ] }, { @@ -345,7 +351,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Beispiele" + "### Examples" ] }, { @@ -446,36 +452,36 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Stile und Farben" + "## Styles and colors" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Farben\n", + "### Colors\n", "\n", - "`Canvas` hat zwei Farbattribute, eines für Striche und eines für Flächen; zudem kann die Transparenz geändert werden.\n", + "`Canvas` has two color attributes, one for strokes and one for areas; the transparency can also be changed.\n", "\n", - "* `stroke_style` erwartet eine gültige HTML-Farbe. Der Standardwert ist schwarz.\n", - "* `fill_style` erwartet eine gültige HTML-Farbe. Der Standardwert ist schwarz.\n", - "* `global_alpha` gibt die Transparenz an. Der Standardwert ist `1.0`." + "* `stroke_style` expects a valid HTML color. The default is black.\n", + "* `fill_style` expects a valid HTML color. The default is black.\n", + "* `global_alpha` indicates the transparency. The default is 1.0." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Linien" + "### Lines" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "#### Linienart\n", + "#### Line style\n", "\n", - "Linien lassen sich durch folgende Attribute beschreiben:\n", + "Lines can be described by the following attributes:\n", "\n", "* `line_width`\n", "* `line_cap`\n", @@ -490,7 +496,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### Linienbreite" + "#### Line width" ] }, { @@ -537,7 +543,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### Linienende" + "#### Line end" ] }, { @@ -602,9 +608,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### Linienverbindung\n", + "#### Line connection\n", "\n", - "legt das Erscheinungsbild der *Ecken* fest, an denen sich Linien treffen." + "defines the appearance of the corners where lines meet." ] }, { @@ -666,7 +672,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### Strichmuster" + "#### Line pattern" ] }, { @@ -721,9 +727,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Text\n", + "## text\n", "\n", - "Es gibt zwei Methoden zur Gestaltung von Text:\n", + "There are two methods of designing text:\n", "\n", "* `fill_text(text, x, y, max_width=None)`\n", "* `stroke_text(text, x, y, max_width=None)`" @@ -793,28 +799,35 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "* `font` gibt den aktuellen Textstil an. Der Standardwert ist `\"12px sans-serif\"`.\n", - "* `text_align` gibt die Textausrichtung an. Mögliche Werte sind `\"start\"`, `\"end\"`, `\"left\"`, `\"right\"` oder `\"center\"` .\n", - "* `text_baseline` gibt die Ausrichtung an der Grundlinie an. Mögliche Werte sind `\"top\"`, `\"hanging\"`, `\"middle\"`, `\"alphabetic\"`, `\"ideographic\"` und `\"bottom\"`. Der Standardwert ist `\"alphabetic\"`.\n", - "* `direction` gibt die Textrichtung an. Mögliche Werte sind `\"ltr\"`, `\"rtl\"`, `\"inherit\"`. Der Standardwert ist `\"inherit\"`. \n", + "font indicates the current text style. The default value is \"12px sans-serif\".\n", + " text_align specifies the text alignment. Possible values are \"start\", \"end\", \"left\", \"right\" or \"center\".\n", + " text_baseline indicates the alignment with the baseline. Possible values are \"top\", \"hanging\", \"middle\", \"alphabetic\", \"ideographic\" and \"bottom\". The default value is \"alphabetic\".\n", + " direction indicates the text direction. Possible values are \"ltr\", \"rtl\", \"inherit\". The default value is \"inherit\".\n", + "\n", + "Of course, fill_style and stroke_style can also be used to color the text.\n", + "\n", + "* `font` indicates the current text style. The default value is `\"12px sans-serif\"`.\n", + "* `text_align` specifies the text alignment. Possible values are `\"start\"`, `\"end\"`, `\"left\"`, `\"right\"` or `\"center\"` .\n", + "* `text_baseline` indicates the alignment with the baseline. Possible values are `\"top\"`, `\"hanging\"`, `\"middle\"`, `\"alphabetic\"`, `\"ideographic\"` and `\"bottom\"`. The default value is `\"alphabetic\"`.\n", + "* `direction` indicates the text direction. Possible values are `\"ltr\"`, `\"rtl\"`, `\"inherit\"`. The default value is `\"inherit\"`. \n", "\n", - "Selbstverständlich kann auch `fill_style` und `stroke_style` zum EInfürben der Text verwendet werden." + "Of course, `fill_style` and `stroke_style` can also be used to color the text." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Bilder" + "## Images" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### aus einem Numpy-Array\n", + "### … from a Numpy array\n", "\n", - "Mit `put_image_data(image_data, dx, dy)` lässt sich ein Bild darstellen wobei `image_data` ein Numyp-Array angibt und `dx` und `dy` das obere linke Eck des Bildes. " + "With `put_image_data(image_data, dx, dy)` an image can be displayed, where `image_data` specifies a Numpy array and `dx` and `dy` the upper left corner of the image." ] }, { @@ -865,30 +878,30 @@ "source": [ "## Status\n", "\n", - "Der Status kann mit zwei Werten angegeben werden:\n", + "The status can be specified with two values:\n", "\n", - "* `save()` speichert den Status des Canvas-Elements\n", - "* `restore()` stellt den zuletzt gespeicherten Status des Canvas-Elements wieder her wobei diese Methode beliebig oft aufgerufen werden kann." + "* `save()` saves the status of the canvas element.\n", + "* `restore()` restores the last saved status of the canvas element. This method can be called as often as required." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Transformationen\n", + "## Transformations\n", "\n", - "* `translate(x, y)` verschiebt das Canvas-Element\n", - "* `rotate(angle)` rotiert das Canvas-Element im Uhrzeigersinn\n", - "* `scale(x, y=None)` skaliert das Canvas-Element" + "* `translate(x, y)` moves the canvas element\n", + "* `rotate(angle)` rotates the canvas element clockwise\n", + "* `scale(x, y=None)` scales the canvas element" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Siehe auch\n", + "## See also\n", "\n", - "* [API-Referenz](https://ipycanvas.readthedocs.io/en/latest/api.html)" + "* [API reference](https://ipycanvas.readthedocs.io/en/latest/api.html)" ] } ], diff --git a/docs/workspace/jupyter/ipywidgets/libs/ipympl.ipynb b/docs/workspace/jupyter/ipywidgets/libs/ipympl.ipynb index 0ddc582b..e6ffbeba 100644 --- a/docs/workspace/jupyter/ipywidgets/libs/ipympl.ipynb +++ b/docs/workspace/jupyter/ipywidgets/libs/ipympl.ipynb @@ -6,7 +6,7 @@ "source": [ "# `ipympl`\n", "\n", - "Da sich das Jupyter-Widget-Ökosystem zu schnell entwickelt, haben die Matplotlib-Entwickler beschlossen, die Unterstützung in ein eigenes Modul auszulagern: `ipympl` oder [jupyter-matplotlib](https://github.com/matplotlib/jupyter-matplotlib)." + "Since the Jupyter widget ecosystem is developing too quickly, the Matplotlib developers have decided to outsource the support to a separate module: `ipympl` or [jupyter-matplotlib](https://github.com/matplotlib/jupyter-matplotlib)." ] }, { @@ -15,7 +15,7 @@ "source": [ "## Installation\n", "\n", - "`ipympl` wird sowohl im Kernel- wie auch im Jupyter-Environment installiert mit\n", + "`ipympl` is installed in both the kernel and the Jupyter environment\n", "\n", "```\n", "pipenv install ipympl\n", @@ -25,7 +25,7 @@ "…\n", "```\n", "\n", - "Anschließend könnt ihr das Jupyter-Backend in Notebooks aktivieren, indem ihr die folgende *Matplotlib-Magic* verwendet:" + "Then you can activate the Jupyter backend in notebooks by using the following *Matplotlib-Magic*:" ] }, { @@ -41,14 +41,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiele" + "## Examples" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Einfache Matplotlib-Interaktion " + "### Simple Matplotlib interaction " ] }, { @@ -84,7 +84,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### 3D-Plot: [subplot3d_demo.py](https://matplotlib.org/examples/mplot3d/subplot3d_demo.html)" + "### 3D plot: [subplot3d_demo.py](https://matplotlib.org/examples/mplot3d/subplot3d_demo.html)" ] }, { @@ -128,7 +128,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Komplexeres Beispiel aus der [Matplotlib-Galerie](https://matplotlib.org/gallery.html)" + "### More complex example from the [Matplotlib gallery](https://matplotlib.org/gallery.html)" ] }, { diff --git a/docs/workspace/jupyter/ipywidgets/libs/ipysheet.ipynb b/docs/workspace/jupyter/ipywidgets/libs/ipysheet.ipynb index fc8a8e88..53b89bd2 100644 --- a/docs/workspace/jupyter/ipywidgets/libs/ipysheet.ipynb +++ b/docs/workspace/jupyter/ipywidgets/libs/ipysheet.ipynb @@ -6,7 +6,7 @@ "source": [ "# `ipysheet`\n", "\n", - "[ipysheet](https://github.com/QuantStack/ipysheet) verbindet ipywidgets mit tabellarischen Daten. Es fügt im Wesentlichen zwei Widgets hinzu: ein _Cell widget_ und ein _Sheet widget_. Darüberhinaus gibt es noch Hilfsfunktionen zum Erstellen von Tabellenzeilen und -spalten sowie zur Formatierung und Gestaltung von Zellen." + "[ipysheet](https://github.com/QuantStack/ipysheet) connects ipywidgets with tabular data. It basically adds two widgets: a _Cell widget_ and a _Sheet widget_. There are also auxiliary functions for creating table rows and columns as well as for formatting and designing cells." ] }, { @@ -15,7 +15,7 @@ "source": [ "## Installation\n", "\n", - "`ipysheet` lässt sich einfach mit Pipenv installieren:\n", + "`ipysheet` can be easily installed with Pipenv:\n", "\n", "```\n", "$ pipenv install ipysheet\n", @@ -42,7 +42,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Zellformatierung" + "## Cell formatting" ] }, { @@ -80,14 +80,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiele" + "## Examples" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Interaktive Tabelle" + "### Interactive table" ] }, { @@ -216,7 +216,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Tabellensuche" + "### Table search" ] }, { @@ -267,7 +267,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Plotten editierbarer Tabellen" + "### Plot editable tables" ] }, { @@ -324,7 +324,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Zum Weiterlesen\n", + "## For further reading\n", "\n", "* [Interactive spreadsheets in Jupyter](https://towardsdatascience.com/interactive-spreadsheets-in-jupyter-32ab6ec0f4ff)\n", "* [GitHub](https://github.com/QuantStack/ipysheet)\n", diff --git a/docs/workspace/jupyter/ipywidgets/libs/ipyvuetify.ipynb b/docs/workspace/jupyter/ipywidgets/libs/ipyvuetify.ipynb index d142cef1..f8a9cce8 100644 --- a/docs/workspace/jupyter/ipywidgets/libs/ipyvuetify.ipynb +++ b/docs/workspace/jupyter/ipywidgets/libs/ipyvuetify.ipynb @@ -6,7 +6,7 @@ "source": [ "# `ipyvuetify`\n", "\n", - "[ipyvuetify](https://github.com/mariobuikhuizen/ipyvuetify) liefert Jupyter-Widgets, die auf [vuetify](https://v15.vuetifyjs.com/en/)-UI-Komponenten basieren und das [Material Design](https://material.io/) von Google mit dem [Vue.js-Framework](https://v15.vuetifyjs.com/en/) implementieren." + "[ipyvuetify](https://github.com/mariobuikhuizen/ipyvuetify) provides Jupyter widgets based on [vuetify](https://v15.vuetifyjs.com/en/) UI components and implementing Google’s [Material Design](https://material.io/) with the [Vue.js-Framework](https://v15.vuetifyjs.com/en/) framework." ] }, { @@ -29,14 +29,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Beispiele" + "## Examples" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Importe" + "### Imports" ] }, { @@ -56,7 +56,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Menü" + "### Menu" ] }, { @@ -386,7 +386,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Reiter" + "### Tabs" ] }, { @@ -422,7 +422,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Akkordeon" + "### Accordion" ] }, { @@ -463,19 +463,19 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In der [Vuetify-Dokumentation](https://v15.vuetifyjs.com/en/components/buttons#buttons) könnt ihr nach allen verfügbaren Komponenten und Attributen suchen. Dabei orientiert sich Ipyvuetify an der Syntax von Vue.js- und Vuetify, aber es gibt auch einige Unterschiede:\n", + "You can search for all available components and attributes in the [Vuetify documentation](https://v15.vuetifyjs.com/en/components/buttons#buttons). Ipyvuetify is based on the syntax of Vue.js- and Vuetify, but there are also some differences:\n", "\n", - "| Beschreibung | Vuetify | ipyvuetify |\n", + "| Description | Vuetify | ipyvuetify |\n", "| ------------- | --------- | ------------ |\n", - "| Komponentennamen werden in CamelCase geschrieben und der `v`-Präfix entfernt | `` | `ListTile(…)` |\n", - "| Untergeordnete Komponenten und Text werden im Traitlet für untergeordnete Elemente definiert | `text ` | `Btn(children=['text', Icon(…)])` |\n", - "| Flag-Attribute erfordern einen booleschen Wert | `