Metadata-Version: 2.1
Name: cython-extensions-sc2
Version: 0.13.2
Summary: 
License: GPL-3.0
Author: Tom Kerr
Author-email: tomkerrdev@gmail.com
Requires-Python: >=3.11,<3.14
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: burnysc2 (>=7.0.0)
Requires-Dist: jupyterlab (>=4.4.6,<5.0.0)
Description-Content-Type: text/markdown

[![Testing](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/test.yml/badge.svg)](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/test.yml)
[![Deploy Documentation](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/pages.yml/badge.svg)](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/pages.yml)
<br>

# cython-extensions-sc2

[API Documentation](https://aressc2.github.io/cython-extensions-sc2/) - for a full list of included functions.

`cython-extensions-sc2` is a library designed for the [python-sc2](https://github.com/BurnySc2/python-sc2) API. 
Its purpose is to offer optimized Cython alternatives for commonly used functions, 
along with additional useful custom functions.

<b>Note: This library is included for `ares-sc2` users by default, no further setup is required.</b>

This library also supports `python-sc2` and `sharpy-sc2` bots, see Getting Started below.

Example speedups, results may vary depending on machine and exact scenario.
This is by no means a list of all functionality offered.

| python-sc2 function              | cython speedup                           |
|----------------------------------|------------------------------------------|
| `units.closest_to`               | 6.85 - 13x speedup depending on scenario |
| `distance_to`                    | 3 to 7x speedup depending on scenario    |
| `position.center`                | 2x speedup                               |
| `already_pending` for units      | 6.62x speedup                            |
| `already_pending` for structures | 4x speedup                               |
| `units.in_attack_range`          | 2.05x speedup                            |
| `units.sorted_by_distance_to`    | 8.62x speedup                            |
| `unit.is_facing`                 | 9.1x speedup                             |
| `Point2.towards`                 | 14.29x speedup                           |
| `has_creep`                      | 4 - 5x speedup                           |
| `in_pathing_grid`                | 4 - 5x speedup                           |
| `closer_than`                    | 12x speedup                              |
| `further_than`                   | 12x speedup                              |


Tip: use `cy_distance_to_squared` where possible for extra 1.3x speedup.

## Getting started

To quickly get up and running locally (for python versions 3.11, 3.12), install `cython-extensions-sc2` with:

`pip install cython-extensions-sc2`

## Type Safety

`cython-extensions-sc2` includes type safety checking to prevent your bot failing with silent errors.
This is disabled by default for pure performance reasons, to enable it call `enable_safe_mode(True)`.

```python
from cython_extensions import enable_safe_mode
# immediately after importing any cython functions
enable_safe_mode(True)
```

Even with safe mode disabled, there will still be some function overhead, but it should be negligible.
However, if you want to squeeze every last bit of performance out of your bot, you can import cython functions
directly from the cython files to avoid using the type checker functionality all together.

Example using `cy_closest_to` turning off safe mode for some performance:
```python
from cython_extensions import cy_closest_to, enable_safe_mode
enable_safe_mode(False)
```

You could instead import `cy_closest_to` directly:
```python
from cython_extensions.units_utils import cy_closest_to
```

## Shipping to ladder
When shipping to [ladder](https://aiarena.net/), grab `ubuntu-latest_python3.12.zip` from releases in this repo
and extract `cython_extensions` directory within the zip to the root of your bot's directory, like so:

```
MyBot
└───cython_extensions
│   └───cython-extensions library files
└───your bot files and directories
```

## Alternative local setup
If you already have a `python-sc2`, or `sharpy-sc2` development environment setup,
then `cython-extensions` should work out the box with your bot without the need to install extra requirements. Simply check out the releases on this
repo and download the correct `zip` for your system.

![release](https://github.com/AresSC2/cython-extensions-sc2/assets/63355562/3c5084ee-5d61-4446-a0dc-4d0ce3421b34)

For example a Windows user should download `windows-latest_python3.12.zip`.

Inside this zip you will find a `cython_extensions` directory, this should be placed in your bot's root directory
like so:
```
MyBot
└───cython_extensions
│   └───cython-extensions library files
└───your bot files and directories
```

### Start using `cython-extensions-sc2`
For ease of use all cython functions are importable via the main module, for example:
```python
from cython_extensions import cy_distance_to, cy_attack_ready, cy_closest_to
```
note: in this project all library functions have a `cy_` prefix to prevent confusion with python alternatives.

## Contributor / Cloning the project
Install [poetry](https://python-poetry.org/) if you do not already have it installed.

Then to setup a full development environment run:
`poetry install --with dev,test,docs,semver`

This will set up a new environment, install all required dependencies and compile the cython code for your system.

If you modify the cython code, run `poetry build` to compile it.

### Jupyter Notebooks
Run `poetry run jupyter notebook` to open jupyter notebook in the environment. See the notebooks 
directory for examples. Use `template_notebook.ipynb` as a starting point for your own notebooks.

### Updating ids
`ability_mapping.pyx` ids are generated via a script, these should be updated after a new SC2 version is released.
Run `poetry run python scripts/update_ability_mapping` to update the ids.

### Run Test Bot
Edit the map in `bot_test.py` and run with:
`poetry run python tests/bot_test.py`

## Contributing
Contributors are very welcome! There are many missing alternative `python-sc2` functions, and if you're 
into optimization, the existing functions could likely be improved.

### Adding new functions
If you want to add a new function, please add it to the relevant '.pyx' and '.pyi' files. See 
existing functions for examples. Please also add tests for your function in the `tests` directory.

Additionally, the new function should be added to the type checking system in `cython_extensions/type_checking`
First add a validation function inside `cython_extensions/type_checking/validators.py` using the
existing examples as guidance.

Then add a `safe_wrapper` function inside `cython_extensions/type_checking/safe_wrappers.py` using the
existing examples as an example. Ensure your new function is exported at the bottom of this file.
Preferably check the new function works in a real bot before submitting a PR. You can use `tests/bot_test.py`
to test your function.`



### Commit messages
Please use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) if you choose to contribute, 
it helps the automatic releases detect
a new version and generates an accurate changelog.

Example git messages:

`feat: add new cython function`

`fix: fixed buggy function`

`test: add new test`

`ci: update github workflow`

`docs: add new docs`

`chore: add dependency`


