openai/openai-python
Publicmirrored from https://github.com/openai/openai-pythonAvailable
CONTRIBUTING.md
125lines · modecode
| 1 | ## Setting up the environment |
| 2 | |
| 3 | ### With Rye |
| 4 | |
| 5 | We use [Rye](https://rye-up.com/) to manage dependencies so we highly recommend [installing it](https://rye-up.com/guide/installation/) as it will automatically provision a Python environment with the expected Python version. |
| 6 | |
| 7 | After installing Rye, you'll just have to run this command: |
| 8 | |
| 9 | ```sh |
| 10 | $ rye sync --all-features |
| 11 | ``` |
| 12 | |
| 13 | You can then run scripts using `rye run python script.py` or by activating the virtual environment: |
| 14 | |
| 15 | ```sh |
| 16 | $ rye shell |
| 17 | # or manually activate - https://docs.python.org/3/library/venv.html#how-venvs-work |
| 18 | $ source .venv/bin/activate |
| 19 | |
| 20 | # now you can omit the `rye run` prefix |
| 21 | $ python script.py |
| 22 | ``` |
| 23 | |
| 24 | ### Without Rye |
| 25 | |
| 26 | Alternatively if you don't want to install `Rye`, you can stick with the standard `pip` setup by ensuring you have the Python version specified in `.python-version`, create a virtual environment however you desire and then install dependencies using this command: |
| 27 | |
| 28 | ```sh |
| 29 | $ pip install -r requirements-dev.lock |
| 30 | ``` |
| 31 | |
| 32 | ## Modifying/Adding code |
| 33 | |
| 34 | Most of the SDK is generated code, and any modified code will be overridden on the next generation. The |
| 35 | `src/openai/lib/` and `examples/` directories are exceptions and will never be overridden. |
| 36 | |
| 37 | ## Adding and running examples |
| 38 | |
| 39 | All files in the `examples/` directory are not modified by the Stainless generator and can be freely edited or |
| 40 | added to. |
| 41 | |
| 42 | ```bash |
| 43 | # add an example to examples/<your-example>.py |
| 44 | |
| 45 | #!/usr/bin/env -S rye run python |
| 46 | … |
| 47 | ``` |
| 48 | |
| 49 | ``` |
| 50 | chmod +x examples/<your-example>.py |
| 51 | # run the example against your api |
| 52 | ./examples/<your-example>.py |
| 53 | ``` |
| 54 | |
| 55 | ## Using the repository from source |
| 56 | |
| 57 | If you’d like to use the repository from source, you can either install from git or link to a cloned repository: |
| 58 | |
| 59 | To install via git: |
| 60 | |
| 61 | ```bash |
| 62 | pip install git+ssh://git@github.com:openai/openai-python.git |
| 63 | ``` |
| 64 | |
| 65 | Alternatively, you can build from source and install the wheel file: |
| 66 | |
| 67 | Building this package will create two files in the `dist/` directory, a `.tar.gz` containing the source files and a `.whl` that can be used to install the package efficiently. |
| 68 | |
| 69 | To create a distributable version of the library, all you have to do is run this command: |
| 70 | |
| 71 | ```bash |
| 72 | rye build |
| 73 | # or |
| 74 | python -m build |
| 75 | ``` |
| 76 | |
| 77 | Then to install: |
| 78 | |
| 79 | ```sh |
| 80 | pip install ./path-to-wheel-file.whl |
| 81 | ``` |
| 82 | |
| 83 | ## Running tests |
| 84 | |
| 85 | Most tests will require you to [setup a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests. |
| 86 | |
| 87 | ```bash |
| 88 | # you will need npm installed |
| 89 | npx prism path/to/your/openapi.yml |
| 90 | ``` |
| 91 | |
| 92 | ```bash |
| 93 | rye run pytest |
| 94 | ``` |
| 95 | |
| 96 | ## Linting and formatting |
| 97 | |
| 98 | This repository uses [ruff](https://github.com/astral-sh/ruff) and |
| 99 | [black](https://github.com/psf/black) to format the code in the repository. |
| 100 | |
| 101 | To lint: |
| 102 | |
| 103 | ```bash |
| 104 | rye run lint |
| 105 | ``` |
| 106 | |
| 107 | To format and fix all ruff issues automatically: |
| 108 | |
| 109 | ```bash |
| 110 | rye run format |
| 111 | ``` |
| 112 | |
| 113 | ## Publishing and releases |
| 114 | |
| 115 | Changes made to this repository via the automated release PR pipeline should publish to PyPI automatically. If |
| 116 | the changes aren't made through the automated pipeline, you may want to make releases manually. |
| 117 | |
| 118 | ### Publish with a GitHub workflow |
| 119 | |
| 120 | You can release to package managers by using [the `Publish PyPI` GitHub action](https://www.github.com/openai/openai-python/actions/workflows/publish-pypi.yml). This will require a setup organization or repository secret to be set up. |
| 121 | |
| 122 | ### Publish manually |
| 123 | |
| 124 | If you need to manually release a package, you can run the `bin/publish-pypi` script with an `PYPI_TOKEN` set on |
| 125 | the environment. |