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