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
`sentry-sdk` is an ordinary Python package. You can install it with `pip
4
-
install -e .` into some virtualenv, edit the sourcecode and test out your
5
-
changes manually.
3
+
We welcome contributions to python-sentry by the community. See the [Contributing to Docs](https://docs.sentry.io/contributing/) page if you want to fix or update the documentation on the website.
6
4
7
-
## Community
5
+
## How to report a problem
8
6
9
-
The public-facing channels for support and development of Sentry SDKs can be found on [Discord](https://discord.gg/Ww9hbqr).
7
+
Please search the [issue tracker](https://github.com/getsentry/sentry-python/issues) before creating a new issue (a problem or an improvement request). Please also ask in our [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr) before submitting a new issue. There is a ton of great people in our Discord community ready to help you!
10
8
11
-
## Running tests and linters
9
+
If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes.
12
10
13
-
Make sure you have `virtualenv` installed, and the Python versions you care
14
-
about. You should have Python 2.7 and the latest Python 3 installed.
11
+
## Submitting changes
15
12
16
-
We have a `Makefile` that is supposed to help people get started with hacking
17
-
on the SDK without having to know or understand the Python ecosystem. You don't
18
-
need to `workon` or `bin/activate` anything, the `Makefile` will do everything
19
-
for you. Run `make` or `make help` to list commands.
13
+
- Setup the development environment.
14
+
- Clone sentry-python and prepare necessary changes.
15
+
- Add tests for your changes to `tests/`.
16
+
- Run tests and make sure all of them pass.
17
+
- Submit a pull request, referencing any issues it addresses.
18
+
19
+
We will review your pull request as soon as possible.
Make sure that you have Python 3 installed. Version 3.7 or higher is required to run style checkers on pre-commit. On macOS, we recommend using brew to install Python. For Windows, we recommend an official python.org release.
31
+
32
+
### Create a virtual environment:
33
+
34
+
```bash
35
+
cd sentry-python
36
+
37
+
python -m venv .env
38
+
39
+
source .env/bin/activate
40
+
41
+
pip install -e .
42
+
```
43
+
44
+
**Hint:** Sometimes you need a sample project to run your new changes to sentry-python. In this case install the sample project in the same virtualenv and you should be good to go because the ` pip install -e .` from above installed your local sentry-python in editable mode. So you can just hack away!
45
+
46
+
### Install coding style pre-commit hooks:
47
+
48
+
```bash
49
+
cd sentry-python
50
+
51
+
pip install -r linter-requirements.txt
52
+
53
+
pip install pre-commit
54
+
55
+
pre-commit install
56
+
```
57
+
58
+
That's it. You should be ready to make changes, run tests, and make commits! If you experience any problems, please don't hesitate to ping us in our [Discord Community](https://discord.com/invite/Ww9hbqr).
59
+
60
+
## Running tests
61
+
62
+
We have a `Makefile` to help people get started with hacking on the SDK
63
+
without having to know or understand the Python ecosystem.
64
+
Run `make` or `make help` to list commands.
65
+
66
+
So the simplest way to run tests is:
67
+
68
+
```bash
69
+
cd sentry-python
70
+
71
+
make tests
72
+
```
73
+
74
+
This will use [Tox](https://tox.wiki/en/latest/) to run our whole test suite
75
+
under Python 2.7 and Python 3.7.
20
76
21
77
Of course you can always run the underlying commands yourself, which is
22
78
particularly useful when wanting to provide arguments to `pytest` to run
23
-
specific tests. If you want to do that, we expect you to know your way around
24
-
Python development. To get started, clone the SDK repository, cd into it, set
25
-
up a virtualenv and run:
79
+
specific tests:
80
+
81
+
```bash
82
+
cd sentry-python
26
83
27
-
# This is "advanced mode". Use `make help` if you have no clue what's
28
-
# happening here!
84
+
# create virtual environment
85
+
python -m venv .env
29
86
30
-
pip install -e .
31
-
pip install -r test-requirements.txt
87
+
# activate virtual environment
88
+
source .env/bin/activate
32
89
33
-
pytest tests/
90
+
# install sentry-python
91
+
pip install -e .
92
+
93
+
# install requirements
94
+
pip install -r test-requirements.txt
95
+
96
+
# run tests
97
+
pytest tests/
98
+
```
99
+
100
+
If you want to run the tests for a specific integration you should do so by doing this:
101
+
102
+
```bash
103
+
pytest -rs tests/integrations/flask/
104
+
```
105
+
106
+
**Hint:** Tests of integrations need additional dependencies. The switch `-rs` will show you why tests where skipped and what dependencies you need to install for the tests to run. (You can also consult the [tox.ini](tox.ini) file to see what dependencies are installed for each integration)
34
107
35
108
## Releasing a new version
36
109
@@ -48,42 +121,48 @@ The usual release process goes like this:
48
121
49
122
1. Write the integration.
50
123
51
-
* Instrument all application instances by default. Prefer global signals/patches instead of configuring a specific instance. Don't make the user pass anything to your integration for anything to work. Aim for zero configuration.
124
+
- Instrument all application instances by default. Prefer global signals/patches instead of configuring a specific instance. Don't make the user pass anything to your integration for anything to work. Aim for zero configuration.
52
125
53
-
* Everybody monkeypatches. That means:
126
+
- Everybody monkeypatches. That means:
54
127
55
-
* Make sure to think about conflicts with other monkeypatches when monkeypatching.
128
+
- Make sure to think about conflicts with other monkeypatches when monkeypatching.
56
129
57
-
* You don't need to feel bad about it.
130
+
- You don't need to feel bad about it.
58
131
59
-
* Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
132
+
- Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
60
133
61
-
* Allow the user to disable the integration by changing the client. Check `Hub.current.get_integration(MyIntegration)` from within your signal handlers to see if your integration is still active before you do anything impactful (such as sending an event).
134
+
- Allow the user to disable the integration by changing the client. Check `Hub.current.get_integration(MyIntegration)` from within your signal handlers to see if your integration is still active before you do anything impactful (such as sending an event).
62
135
63
136
2. Write tests.
64
137
65
-
* Think about the minimum versions supported, and test each version in a separate env in `tox.ini`.
138
+
- Think about the minimum versions supported, and test each version in a separate env in `tox.ini`.
66
139
67
-
* Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
140
+
- Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
68
141
69
142
3. Update package metadata.
70
143
71
-
* We use `extras_require` in `setup.py` to communicate minimum version requirements for integrations. People can use this in combination with tools like Poetry or Pipenv to detect conflicts between our supported versions and their used versions programmatically.
144
+
- We use `extras_require` in `setup.py` to communicate minimum version requirements for integrations. People can use this in combination with tools like Poetry or Pipenv to detect conflicts between our supported versions and their used versions programmatically.
72
145
73
-
Do not set upper-bounds on version requirements as people are often faster in adopting new versions of a web framework than we are in adding them to the test matrix or our package metadata.
146
+
Do not set upper-bounds on version requirements as people are often faster in adopting new versions of a web framework than we are in adding them to the test matrix or our package metadata.
74
147
75
148
4. Write the [docs](https://github.com/getsentry/sentry-docs). Answer the following questions:
76
149
77
-
* What does your integration do? Split in two sections: Executive summary at top and exact behavior further down.
150
+
- What does your integration do? Split in two sections: Executive summary at top and exact behavior further down.
78
151
79
-
* Which version of the SDK supports which versions of the modules it hooks into?
152
+
- Which version of the SDK supports which versions of the modules it hooks into?
80
153
81
-
* One code example with basic setup.
154
+
- One code example with basic setup.
82
155
83
-
* Make sure to add integration page to `python/index.md` (people forget to do that all the time).
156
+
- Make sure to add integration page to `python/index.md` (people forget to do that all the time).
84
157
85
-
Tip: Put most relevant parts wrapped in `<!--WIZARD-->..<!--ENDWIZARD-->` tags for usage from within the Sentry UI.
158
+
Tip: Put most relevant parts wrapped in `<!--WIZARD-->..<!--ENDWIZARD-->` tags for usage from within the Sentry UI.
86
159
87
160
5. Merge docs after new version has been released (auto-deploys on merge).
88
161
89
162
6. (optional) Update data in [`sdk_updates.py`](https://github.com/getsentry/sentry/blob/master/src/sentry/sdk_updates.py) to give users in-app suggestions to use your integration. May not be applicable or doable for all kinds of integrations.
Copy file name to clipboardExpand all lines: README.md
+77-11Lines changed: 77 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -6,32 +6,98 @@
6
6
7
7
_Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us [<kbd>**Check out our open positions**</kbd>](https://sentry.io/careers/)_
This is the next line of the Python SDK for [Sentry](http://sentry.io/), intended to replace the `raven` package on PyPI.
15
+
This is the official Python SDK for [Sentry](http://sentry.io/)
16
+
17
+
---
18
+
19
+
## Migrate From sentry-raven
20
+
21
+
The old `raven-python` client has entered maintenance mode and was moved [here](https://github.com/getsentry/raven-python).
22
+
23
+
If you're using `raven-python`, we recommend you to migrate to this new SDK. You can find the benefits of migrating and how to do it in our [migration guide](https://docs.sentry.io/platforms/python/migration/).
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
88
+
89
+
## Getting help/support
90
+
91
+
If you need help setting up or configuring the Python SDK (or anything else in the Sentry universe) please head over to the [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr). There is a ton of great people in our Discord community ready to help you!
92
+
93
+
## Resources
32
94
33
-
Please refer to [CONTRIBUTING.md](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md).
0 commit comments