Metadata-Version: 2.4
Name: tidygraph
Version: 0.2.4
Summary: tidy-like interface for network manipulation and visualization in Python
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: igraph>=1.0.0
Requires-Dist: narwhals>=2.15.0
Requires-Dist: pandas>=3.0.0
Requires-Python: >=3.13
Project-URL: issues, https://github.com/yiping-allison/tidygraph-py/issues
Project-URL: repository, https://github.com/yiping-allison/tidygraph-py
Description-Content-Type: text/markdown

# tidygraph

[![pypi](https://img.shields.io/pypi/v/tidygraph.svg)](https://pypi.org/project/tidygraph/)
![pyversion](https://img.shields.io/pypi/pyversions/tidygraph.svg)
[![ci](https://github.com/yiping-allison/tidygraph-py/actions/workflows/ci.yaml/badge.svg)](https://github.com/yiping-allison/tidygraph-py/actions/workflows/ci.yaml)

A tidy-like API for network manipulation with the [igraph](https://github.com/igraph/python-igraph) library inspired by:

- [tidygraph](https://github.com/thomasp85/tidygraph)
- [tidygraphtool](https://github.com/jstonge/tidygraphtool/tree/main)

The main purpose of using this library on top of `python-igraph` is to support relational data manipulation.

```python
tg = Tidygraph.from_dataframe(...)
tg.activate(ActiveType.EDGES).join(..., how="outer").mutate({"rank": lambda x: 1.0 - x["score"]})
```

> [!IMPORTANT]
> This library is experimental, and updates may be infrequent. Use at your own risk.

## 🧑‍💻 Development

The easiest way to get started with development is through [`nix`](https://nixos.org/) and related ecosystem tools.

I recommend installing nix using either options:

- [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer)
- [Official Nix installer](https://github.com/NixOS/nix-installer)

> [!NOTE]
> The nix installer provided by the official nix team (since writing, 2026-01-16) is experimental. As a general rule of thumb,
> choose to install from Determinate Nix if you prefer the [additional functionalities](https://determinate.systems/blog/installer-dropping-upstream/)
> provided by the Determinate Nix team, otherwise, use the experimental installer for upstream.

Additionally, you will need [`direnv`](https://direnv.net/) and [`nix-direnv`](https://github.com/nix-community/nix-direnv?tab=readme-ov-file).

Most (if not all) `nix` development workflows use direnv to auto-load the nix shell environment.

The main editor of choice is [VSCode](https://code.visualstudio.com/download). Recommended extensions are included in the [workspace](./tidygraph.code-workspace) file.

The environment should just work if everything is setup correctly!

## 🚑️ FAQ

### Nix, Python, and VSCode

Unfortunately VSCode does not have a programmatic way to set which python interpreter to use. Because the python environment is managed by nix, and nix installs/builds
packages in a non-standard location, VSCode cannot auto-detect where your packages are.

You will need to update the python interpreter path whenever your nix shell environment updates.

The easiest way to do this is the following:

```sh
# print the python interpreter you are currently tracking
which python
```

The path should look something like `/nix/store/XXXXXXXXXXXXXXXXXX-venv/bin/python`. This is the python virtual environment generated by `pyproject-nix` and `uv2nix`.

Update the interpreter path in VSCode's python language settings.

> [!TIP]
> You can find the modal quickly using the command palette and searching `Python: Select Interpreter`.

### Is `Tidygraph` thread-safe?

No. Tidygraph is built on top of `igraph`, which the core C library is inherently not thread-safe.
See [official response](https://github.com/igraph/python-igraph/issues/866) for details.

## 👥 Acknowledgements

This library would not have been possible without existing work from dedicated teams:

- [`python-igraph`](https://github.com/igraph/python-igraph)
- [`tidygraph`](https://github.com/thomasp85/tidygraph/tree/main)

## 🔨 TODO

- Consider adding more verbs available in R `tidygraph`
- Cleanup test code
