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