diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 427d4ad4e4..732855150e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,36 +1,109 @@ -# How to contribute to the Sentry Python SDK +# Contributing to Sentry SDK for Python -`sentry-sdk` is an ordinary Python package. You can install it with `pip -install -e .` into some virtualenv, edit the sourcecode and test out your -changes manually. +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. -## Community +## How to report a problem -The public-facing channels for support and development of Sentry SDKs can be found on [Discord](https://discord.gg/Ww9hbqr). +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! -## Running tests and linters +If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes. -Make sure you have `virtualenv` installed, and the Python versions you care -about. You should have Python 2.7 and the latest Python 3 installed. +## Submitting changes -We have a `Makefile` that is supposed to help people get started with hacking -on the SDK without having to know or understand the Python ecosystem. You don't -need to `workon` or `bin/activate` anything, the `Makefile` will do everything -for you. Run `make` or `make help` to list commands. +- Setup the development environment. +- Clone sentry-python and prepare necessary changes. +- Add tests for your changes to `tests/`. +- Run tests and make sure all of them pass. +- Submit a pull request, referencing any issues it addresses. + +We will review your pull request as soon as possible. +Thank you for contributing! + +## Development environment + +### Clone the repo: + +```bash +git clone git@github.com:getsentry/sentry-python.git +``` + +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. + +### Create a virtual environment: + +```bash +cd sentry-python + +python -m venv .env + +source .env/bin/activate + +pip install -e . +``` + +**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! + +### Install coding style pre-commit hooks: + +```bash +cd sentry-python + +pip install -r linter-requirements.txt + +pip install pre-commit + +pre-commit install +``` + +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). + +## Running tests + +We have a `Makefile` to help people get started with hacking on the SDK +without having to know or understand the Python ecosystem. +Run `make` or `make help` to list commands. + +So the simplest way to run tests is: + +```bash +cd sentry-python + +make tests +``` + +This will use [Tox](https://tox.wiki/en/latest/) to run our whole test suite +under Python 2.7 and Python 3.7. Of course you can always run the underlying commands yourself, which is particularly useful when wanting to provide arguments to `pytest` to run -specific tests. If you want to do that, we expect you to know your way around -Python development. To get started, clone the SDK repository, cd into it, set -up a virtualenv and run: +specific tests: + +```bash +cd sentry-python - # This is "advanced mode". Use `make help` if you have no clue what's - # happening here! +# create virtual environment +python -m venv .env - pip install -e . - pip install -r test-requirements.txt +# activate virtual environment +source .env/bin/activate - pytest tests/ +# install sentry-python +pip install -e . + +# install requirements +pip install -r test-requirements.txt + +# run tests +pytest tests/ +``` + +If you want to run the tests for a specific integration you should do so by doing this: + +```bash +pytest -rs tests/integrations/flask/ +``` + +**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) ## Releasing a new version @@ -48,42 +121,48 @@ The usual release process goes like this: 1. Write the integration. - * 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. + - 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. - * Everybody monkeypatches. That means: + - Everybody monkeypatches. That means: - * Make sure to think about conflicts with other monkeypatches when monkeypatching. + - Make sure to think about conflicts with other monkeypatches when monkeypatching. - * You don't need to feel bad about it. + - You don't need to feel bad about it. - * Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations. + - Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations. - * 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). + - 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). 2. Write tests. - * Think about the minimum versions supported, and test each version in a separate env in `tox.ini`. + - Think about the minimum versions supported, and test each version in a separate env in `tox.ini`. - * Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed. + - Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed. 3. Update package metadata. - * 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. + - 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. - 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. + 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. 4. Write the [docs](https://github.com/getsentry/sentry-docs). Answer the following questions: - * What does your integration do? Split in two sections: Executive summary at top and exact behavior further down. + - What does your integration do? Split in two sections: Executive summary at top and exact behavior further down. - * Which version of the SDK supports which versions of the modules it hooks into? + - Which version of the SDK supports which versions of the modules it hooks into? - * One code example with basic setup. + - One code example with basic setup. - * Make sure to add integration page to `python/index.md` (people forget to do that all the time). + - Make sure to add integration page to `python/index.md` (people forget to do that all the time). - Tip: Put most relevant parts wrapped in `..` tags for usage from within the Sentry UI. +Tip: Put most relevant parts wrapped in `..` tags for usage from within the Sentry UI. 5. Merge docs after new version has been released (auto-deploys on merge). 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. + +## Commit message format guidelines + +See the documentation on commit messages here: + +https://develop.sentry.dev/commit-messages/#commit-message-format diff --git a/README.md b/README.md index ad215fe3e4..65653155b6 100644 --- a/README.md +++ b/README.md @@ -6,32 +6,98 @@ _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 [**Check out our open positions**](https://sentry.io/careers/)_ -# sentry-python - Sentry SDK for Python +# Official Sentry SDK for Python [![Build Status](https://travis-ci.com/getsentry/sentry-python.svg?branch=master)](https://travis-ci.com/getsentry/sentry-python) [![PyPi page link -- version](https://img.shields.io/pypi/v/sentry-sdk.svg)](https://pypi.python.org/pypi/sentry-sdk) [![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/cWnMQeA) -This is the next line of the Python SDK for [Sentry](http://sentry.io/), intended to replace the `raven` package on PyPI. +This is the official Python SDK for [Sentry](http://sentry.io/) + +--- + +## Migrate From sentry-raven + +The old `raven-python` client has entered maintenance mode and was moved [here](https://github.com/getsentry/raven-python). + +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/). + +## Getting Started + +### Install + +```bash +pip install --upgrade sentry-sdk +``` + +### Configuration ```python -from sentry_sdk import init, capture_message +import sentry_sdk -init("https://mydsn@sentry.io/123") +sentry_sdk.init( + "https://12927b5f211046b575ee51fd8b1ac34f@o1.ingest.sentry.io/1", -capture_message("Hello World") # Will create an event. + # Set traces_sample_rate to 1.0 to capture 100% + # of transactions for performance monitoring. + # We recommend adjusting this value in production. + traces_sample_rate=1.0, +) +``` -raise ValueError() # Will also create an event. +### Usage + +```python +from sentry_sdk import capture_message +capture_message("Hello World") # Will create an event in Sentry. + +raise ValueError() # Will also create an event in Sentry. ``` - To learn more about how to use the SDK [refer to our docs](https://docs.sentry.io/platforms/python/) -- Are you coming from raven-python? [Use this cheatsheet](https://docs.sentry.io/platforms/python/migration/) +- Are you coming from raven-python? [Use this migration guide](https://docs.sentry.io/platforms/python/migration/) - To learn about internals use the [API Reference](https://getsentry.github.io/sentry-python/) -# Contributing to the SDK +## Integrations + +- [Django](https://docs.sentry.io/platforms/python/guides/django/) +- [Flask](https://docs.sentry.io/platforms/python/guides/flask/) +- [Bottle](https://docs.sentry.io/platforms/python/guides/bottle/) +- [AWS Lambda](https://docs.sentry.io/platforms/python/guides/aws-lambda/) +- [Google Cloud Functions](https://docs.sentry.io/platforms/python/guides/gcp-functions/) +- [WSGI](https://docs.sentry.io/platforms/python/guides/wsgi/) +- [ASGI](https://docs.sentry.io/platforms/python/guides/asgi/) +- [AIOHTTP](https://docs.sentry.io/platforms/python/guides/aiohttp/) +- [RQ (Redis Queue)](https://docs.sentry.io/platforms/python/guides/rq/) +- [Celery](https://docs.sentry.io/platforms/python/guides/celery/) +- [Chalice](https://docs.sentry.io/platforms/python/guides/chalice/) +- [Falcon](https://docs.sentry.io/platforms/python/guides/falcon/) +- [Quart](https://docs.sentry.io/platforms/python/guides/quart/) +- [Sanic](https://docs.sentry.io/platforms/python/guides/sanic/) +- [Tornado](https://docs.sentry.io/platforms/python/guides/tornado/) +- [Tryton](https://docs.sentry.io/platforms/python/guides/tryton/) +- [Pyramid](https://docs.sentry.io/platforms/python/guides/pyramid/) +- [Logging](https://docs.sentry.io/platforms/python/guides/logging/) +- [Apache Airflow](https://docs.sentry.io/platforms/python/guides/airflow/) +- [Apache Beam](https://docs.sentry.io/platforms/python/guides/beam/) +- [Apache Spark](https://docs.sentry.io/platforms/python/guides/pyspark/) + +## Contributing to the SDK + +Please refer to [CONTRIBUTING.md](CONTRIBUTING.md). + +## Getting help/support + +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! + +## Resources -Please refer to [CONTRIBUTING.md](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md). +- [![Documentation](https://img.shields.io/badge/documentation-sentry.io-green.svg)](https://docs.sentry.io/quickstart/) +- [![Forum](https://img.shields.io/badge/forum-sentry-green.svg)](https://forum.sentry.io/c/sdks) +- [![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/Ww9hbqr) +- [![Stack Overflow](https://img.shields.io/badge/stack%20overflow-sentry-green.svg)](http://stackoverflow.com/questions/tagged/sentry) +- [![Twitter Follow](https://img.shields.io/twitter/follow/getsentry?label=getsentry&style=social)](https://twitter.com/intent/follow?screen_name=getsentry) -# License +## License -Licensed under the BSD license, see [`LICENSE`](https://github.com/getsentry/sentry-python/blob/master/LICENSE) +Licensed under the BSD license, see [`LICENSE`](LICENSE)