# API Reference
Source: https://django-slugify-processor.git-pull.com/api/

(api)=

# API Reference

## Slugify function

```{eval-rst}
.. autofunction:: django_slugify_processor.text.slugify
```

## Template tag

```{eval-rst}
.. autofunction::
    django_slugify_processor.templatetags.slugify_processor.slugify
```

---

# Changelog
Source: https://django-slugify-processor.git-pull.com/history/

(changes)=
(changelog)=
(history)=

```{currentmodule} django_slugify_processor

```

```{include} ../CHANGES

```

---

# django-slugify-processor
Source: https://django-slugify-processor.git-pull.com/

---
hide-toc: true
---

(index)=

# django-slugify-processor

Custom slug processors for Django's `slugify()`.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Quickstart
:link: quickstart
:link-type: doc
Install, configure processors, and start slugifying.
:::

:::{grid-item-card} API Reference
:link: api
:link-type: doc
Every public function and template filter.
:::

:::{grid-item-card} Contributing
:link: project/index
:link-type: doc
Development setup, code style, release process.
:::

::::

## Install

```console
$ pip install django-slugify-processor
```

```console
$ uv add django-slugify-processor
```

## At a glance

Define a processor function:

```python
def my_processor(value):
    value = value.replace("++", "pp")
    return value
```

Register it in your Django settings:

```python
SLUGIFY_PROCESSORS = [
    "myapp.processors.my_processor",
]
```

Use the drop-in replacement for Django's `slugify`:

```python
from django_slugify_processor.text import slugify

slugify("C++")  # 'cpp'
```

```{toctree}
:hidden:

quickstart
api
project/index
history
GitHub <https://github.com/tony/django-slugify-processor>
```

---

# Code Style
Source: https://django-slugify-processor.git-pull.com/project/code-style/

(code-style)=

# Code Style

## ruff

The project uses [ruff](https://ruff.rs) for linting and formatting.

Lint:

```console
$ uv run ruff check .
```

Auto-fix:

```console
$ uv run ruff check . --fix
```

Format:

```console
$ uv run ruff format .
```

## mypy

[mypy](http://mypy-lang.org/) is used for static type checking.

```console
$ uv run mypy .
```

See `pyproject.toml` `[tool.mypy]` for the full configuration.

---

# Development
Source: https://django-slugify-processor.git-pull.com/project/contributing/

# Development

[uv] is a required package to develop.

Install and [git] and [uv]

Clone:

```console
$ git clone https://github.com/tony/django-slugify-processor.git
```

```console
$ cd django-slugify-processor
```

Install packages:

```console
$ uv sync --all-extras --dev
```

[installation documentation]: https://docs.astral.sh/uv/getting-started/installation/
[git]: https://git-scm.com/

## Tests

`uv run py.test`

Helpers: `just test`

## Automatically run tests on file save

1. `just start` (via [pytest-watcher])
2. `just watch-test` (requires installing [entr(1)])

[pytest-watcher]: https://github.com/olzhasar/pytest-watcher

## Documentation

Default preview server: http://localhost:8034

[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.

From home directory: `just start-docs`
From inside `docs/`: `just start`

[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild

### Manual documentation (the hard way)

`cd docs/` and `just html` to build. `just serve` to start http server.

Helpers:
`just build-docs`, `just serve-docs`

Rebuild docs on file change: `just watch-docs` (requires [entr(1)])

Rebuild docs and run server via one terminal: `just dev-docs`

## Formatting / Linting

### ruff

The project uses [ruff] to handle formatting, sorting imports and linting.

````{tab} Command

uv:

```console
$ uv run ruff
```

If you setup manually:

```console
$ ruff check .
```

````

````{tab} just

```console
$ just ruff
```

````

````{tab} Watch

```console
$ just watch-ruff
```

requires [`entr(1)`].

````

````{tab} Fix files

uv:

```console
$ uv run ruff check . --fix
```

If you setup manually:

```console
$ ruff check . --fix
```

````

#### ruff format

[ruff format] is used for formatting.

````{tab} Command

uv:

```console
$ uv run ruff format .
```

If you setup manually:

```console
$ ruff format .
```

````

````{tab} just

```console
$ just ruff-format
```

````

### mypy

[mypy] is used for static type checking.

````{tab} Command

uv:

```console
$ uv run mypy .
```

If you setup manually:

```console
$ mypy .
```

````

````{tab} just

```console
$ just mypy
```

````

````{tab} Watch

```console
$ just watch-mypy
```

requires [`entr(1)`].
````

## Releasing

[uv] handles virtualenv creation, package requirements, versioning,
building, and publishing. Therefore there is no setup.py or requirements files.

Update `__version__` in `__about__.py` and `pyproject.toml`::

    git commit -m 'build(django-slugify-processor): Tag v0.1.1'
    git tag v0.1.1
    git push
    git push --tags

[uv]: https://github.com/astral-sh/uv
[entr(1)]: http://eradman.com/entrproject/
[`entr(1)`]: http://eradman.com/entrproject/
[ruff format]: https://docs.astral.sh/ruff/formatter/
[ruff]: https://ruff.rs
[mypy]: http://mypy-lang.org/

---

# Project
Source: https://django-slugify-processor.git-pull.com/project/

(project)=

# Project

Information for contributors and maintainers.

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Contributing
:link: contributing
:link-type: doc
Development setup, running tests, submitting PRs.
:::

:::{grid-item-card} Code Style
:link: code-style
:link-type: doc
Ruff, mypy, NumPy docstrings, import conventions.
:::

:::{grid-item-card} Releasing
:link: releasing
:link-type: doc
Release checklist and version policy.
:::

::::

```{toctree}
:hidden:

contributing
code-style
releasing
```

---

# Releasing
Source: https://django-slugify-processor.git-pull.com/project/releasing/

(releasing)=

# Releasing

Releases are published to [PyPI](https://pypi.org/project/django-slugify-processor/) via OIDC-trusted publishing from GitHub Actions.

## Steps

1. Update `__version__` in `src/django_slugify_processor/__about__.py` and `version` in `pyproject.toml`.

2. Commit and tag:

```console
$ git commit -m 'build(django-slugify-processor): Tag vX.Y.Z'
```

```console
$ git tag vX.Y.Z
```

3. Push:

```console
$ git push
```

```console
$ git push --tags
```

The CI workflow builds the package and publishes it to PyPI automatically.

---

# Quickstart
Source: https://django-slugify-processor.git-pull.com/quickstart/

(quickstart)=

# Quickstart

## Installation

For latest official version:

```console
$ pip install --user django-slugify-processor
```

Or using uv:

```console
$ uv tool install django-slugify-processor
```

Upgrading:

```console
$ pip install --user --upgrade django-slugify-processor
```

Or with uv:

```console
$ uv tool upgrade django-slugify-processor
```

(developmental-releases)=

### Developmental releases

New versions of django-slugify-processor are published to PyPI as alpha, beta, or release candidates.
In their versions you will see notification like `a1`, `b1`, and `rc1`, respectively.
`1.10.0b4` would mean the 4th beta release of `1.10.0` before general availability.

- [pip]\:

  ```console
  $ pip install --user --upgrade --pre django-slugify-processor
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@next 'django-slugify-processor' --pip-args '\--pre' --force
  // Usage: django-slugify-processor@next [args]
  ```

- [uv tool install][uv-tools]\:

  ```console
  $ uv tool install --prerelease=allow django-slugify-processor
  ```

- [uv]\:

  ```console
  $ uv add django-slugify-processor --prerelease allow
  ```

- [uvx]\:

  ```console
  $ uvx --from 'django-slugify-processor' --prerelease allow django-slugify-processor
  ```

via trunk (can break easily):

- [pip]\:

  ```console
  $ pip install --user -e git+https://github.com/tony/django-slugify-processor.git#egg=django-slugify-processor
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@master 'django-slugify-processor @ git+https://github.com/tony/django-slugify-processor.git@master' --force
  ```

- [uv]\:

  ```console
  $ uv tool install django-slugify-processor --from git+https://github.com/tony/django-slugify-processor.git
  ```

[pip]: https://pip.pypa.io/en/stable/
[pipx]: https://pypa.github.io/pipx/docs/
[uv]: https://docs.astral.sh/uv/
[uv-tools]: https://docs.astral.sh/uv/concepts/tools/
[uvx]: https://docs.astral.sh/uv/guides/tools/

## Usage

For usage instructions, please refer to the [README](https://github.com/tony/django-slugify-processor#readme).

---