You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/user_guide/getting_started.rst
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,9 +9,9 @@ Your usage of the `exasol-toolbox` will likely fall into one of two scenarios:
9
9
10
10
#. Creation of a new project.
11
11
12
-
If you are starting a new project, please read the section :ref:`Create a New Project with Exasol-Toolbox Support <new>`.
12
+
If you are starting a new project, please read the section :ref:`Create a New Project with Exasol-Toolbox Support <new project>`.
13
13
14
-
.. _new:
14
+
.. _new project:
15
15
16
16
Create a New Project with Exasol-Toolbox Support
17
17
-------------------------------------------------
@@ -177,6 +177,8 @@ forward and you just can use the example *noxfile.py* bellow.
177
177
178
178
poetry run pre-commit install --hook-type pre-commit --hook-type pre-push
179
179
180
+
.. _toolbox tasks:
181
+
180
182
7. Go 🥜
181
183
+++++++++++++
182
184
You are ready to use the toolbox. With *nox -l* you can list all available tasks.
@@ -206,3 +208,7 @@ You are ready to use the toolbox. With *nox -l* you can list all available tasks
206
208
207
209
208
210
Enjoy!
211
+
212
+
.. note::
213
+
214
+
The targets and their names may change over time, so the list below may not be up to date, as it is not automatically generated yet. Therefore, if you find discrepancies, please `submit a quick PR <https://github.com/exasol/python-toolbox/compare>`_ to address them.
@@ -14,28 +14,141 @@ What a Project Should Have Before You Migrate
14
14
* The project documentation should be :code:`sphinx` based **[Required]**.
15
15
* Automated tasks within the project should be available as Python code or `Nox`_ tasks. **[Helpful]**
16
16
17
+
.. hint::
18
+
19
+
If you are interested or want to get a good idea of what a bare standard project based on the toolbox should have, excluding the workflows, it is always good to have a look at the `cookiecutter template <https://github.com/exasol/python-toolbox/tree/main/project-template>`_ provided by the toolbox. If the template parts are confusing, you can generate an "empty" project based on it. For details, refer to the :ref:`new project` section.
20
+
17
21
18
22
Iterative Migration Guide
19
23
++++++++++++++++++++++++++
20
24
21
-
Ensure you comply with the basic requirements for your project. Follow these steps for a smooth migration process.
25
+
Ensure you comply with the :ref:`basic requirements<before_you_migrate>` for your project. Follow these steps for a smooth migration process.
22
26
23
27
1. Introduce Nox
24
28
----------------
25
29
As a first step, it is generally advisable to introduce `Nox`_ as a task runner if it is not already in use. Since the :code:`python-toolbox` uses `Nox`_ as its foundation, this simplifies the migration to the toolbox and enhances the user's understanding of `Nox`_.
26
30
27
-
2. Introduce Python-Toolbox Nox Tasks
28
-
-------------------------------------
29
-
This can be done incrementally for different checks of your project, such as linting, typing, documentation, and other tasks.
31
+
2. Introduce the Standard Nox Tasks
32
+
-----------------------------------
33
+
This can be done incrementally for different checks of your project, such as *project*, *test*, *linting*, *documentation*, and *other* tasks.
34
+
As the tasks can be split into roughly five groups, it likely makes sense to integrate at least one group at a time.
35
+
For more details on the current tasks and groups, refer to: :ref:`toolbox tasks`.
36
+
37
+
38
+
Overloading a Task
39
+
__________________
40
+
41
+
In certain cases, it may not be trivial to use the nox task defined within the `python-toolbox`_. In those cases, overloads can be used to provide a smoother or faster transition or to cope with project-specific constraints or needs.
42
+
43
+
For example, if test execution isn't performed in the standard way (e.g., :code:`pytest test/unit`, :code:`pytest test/integration`, :code:`pytest test`).
44
+
45
+
.. warning::
46
+
47
+
While overwriting can be handy and seem like the simplest way to integrate with the toolbox, please take care when making this decision. In the long run, we want to harmonize projects, their builds, execution, testing, and reporting, etc. If you create an overwrite, you are likely to run into troubles later on, e.g., when reporting is required, because you may lack specific artifacts a specific task was creating, etc.
48
+
49
+
So while overwriting can be a good temporary solution, for the long term, it should be considered where to add or use a configuration point within the toolbox to make the standard task work for *all* projects.
50
+
51
+
**Potential options here are:**
52
+
53
+
* Add additional :ref:`plugin extension <plugin support>` points to the toolbox
54
+
* Implement functionality for an :ref:`existing extension point <plugins>` in the `python-toolbox`_
55
+
* Add additional configuration parameters in :code:`noxconfig.py` or :code:`pyproject.toml`
56
+
* Add additional parameterization to tasks
57
+
* :code:`pytest plugins` can take care of a specific test preparation need, e.g., `pytest-backend <https://github.com/exasol/pytest-plugins/tree/main/pytest-backend>`_
58
+
59
+
60
+
.. code-block:: python
61
+
62
+
import nox
63
+
64
+
# imports all nox task provided by the toolbox
65
+
from exasol.toolbox.nox.tasks import*# pylint: disable=wildcard-import disable=unused-wildcard-import
66
+
67
+
# default actions to be run if nothing is explicitly specified with the -s option
68
+
nox.options.sessions = ["project:fix"]
69
+
70
+
@nox.session(name="project:fix", python=False)
71
+
defmy_project_fix_overwrite(session) -> None:
72
+
"""Runs all automated fixes on the code base"""
73
+
74
+
# ATTENTION:
75
+
# In cases where it is reasonable to use "internal" functions, please do those imports
76
+
# within the function to keep them isolated and simplify future removal or replacement.
77
+
from exasol.toolbox.nox._shared import python_files
If test execution isn't performed in the standard way (e.g., :code:`pytest test/unit`, :code:`pytest test/integration`, :code:`pytest test`), you will need to overwrite the test-specific Nox tasks and will not be able to use the default ones.
33
83
34
84
3. Establish a Baseline
35
85
-----------------------
36
-
Configure code quality and settings in the :code:`pyproject.toml` and establish a baseline for your project. If necessary, create tickets for further improvements, especially if major parts of your code need suppression, e.g., in the mypy configuration.
86
+
Configure code quality settings in the :code:`pyproject.toml`file to establish a baseline for your project. If necessary, create tickets for further improvements, especially if major parts of your code require suppression, e.g., in the mypy configuration.
87
+
88
+
**:code:`pyproject.toml` sections to include/consider:**
89
+
90
+
* [tool.coverage.run]
91
+
* [tool.coverage.report]
92
+
* [tool.black]
93
+
* [tool.isort]
94
+
* [tool.pylint.format]
95
+
* [[tool.mypy.overrides]]
96
+
97
+
Example
98
+
_______
99
+
100
+
.. code-block:: toml
101
+
102
+
# Adjust this section if you want fine-grained control
103
+
# over what is considered for code coverage
104
+
[tool.coverage.run]
105
+
relative_files= true
106
+
source= [
107
+
"exasol",
108
+
]
109
+
110
+
# Adjust this section to define the minimum required
111
+
# code coverage for your project
112
+
[tool.coverage.report]
113
+
fail_under=15
114
+
115
+
116
+
# Adjust control maximum line length in your project
117
+
#
118
+
#NOTE:
119
+
# As a rule of thumb, you should not exceed 120 characters,
120
+
# because overly long lines usually accompany higher cyclomatic complexity,
121
+
# as complex functions tend to shift right.
122
+
[tool.black]
123
+
line-length=88
124
+
include="\\.pyi?$"
125
+
126
+
127
+
# Adjust to modify the behavior of import sorting
128
+
[tool.isort]
129
+
profile="black"
130
+
force_grid_wrap=2
131
+
132
+
133
+
# Adjust to define the minimum linting score considered acceptable for your project
134
+
[tool.pylint.master]
135
+
fail-under=7.5
136
+
137
+
# Maximum line length should match what is configured for black.
138
+
# Additionally, a maximum module size can be defined here.
139
+
[tool.pylint.format]
140
+
max-line-length=88
141
+
max-module-lines=800
142
+
143
+
144
+
# Configure exceptions for the type checker
145
+
[[tool.mypy.overrides]]
146
+
module= [
147
+
"test.unit.*",
148
+
"test.integration.*",
149
+
]
150
+
ignore_errors= true
37
151
38
-
TODO: Add config examples and links to config
39
152
40
153
4. Introduce GitHub Workflows
41
154
-----------------------------
@@ -44,13 +157,15 @@ Install the GitHub workflows provided by the :code:`python-toolbox` for futher d
44
157
.. attention::
45
158
This is just guidance. If you have a good understanding of the standard project setup, technologies, and tools used, feel free to diverge at any point or exercise your own judgment.
0 commit comments