|
| 1 | +## Setting up the environment |
| 2 | + |
| 3 | +### With Rye |
| 4 | + |
| 5 | +We use [Rye](https://rye.astral.sh/) to manage dependencies so we highly recommend [installing it](https://rye.astral.sh/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. Modifications to code will be persisted between generations, but may |
| 35 | +result in merge conflicts between manual patches and changes from the generator. The generator will never |
| 36 | +modify the contents of the `src/julep/lib/` and `examples/` directories. |
| 37 | + |
| 38 | +## Adding and running examples |
| 39 | + |
| 40 | +All files in the `examples/` directory are not modified by the generator and can be freely edited or 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:// [email protected]/stainless-sdks/julep-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 require you to [set up 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 mock 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/stainless-sdks/julep-python/actions/workflows/publish-pypi.yml). This requires 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 a `PYPI_TOKEN` set on |
| 125 | +the environment. |
0 commit comments