Treesearch

PyPI

Pattern matching for dependency treebanks.

⚠️ Early Stage: This project is under active development. The API and query language will change as we refine the design.

Overview

Treesearch finds syntactic patterns in dependency-parsed corpora. It reads treebanks in CoNLL-U format and returns all sentences matching a specified structural pattern. Designed for corpus linguistics research on large treebanks with automatic parallel processing for multi-file operations.

Installation

From PyPI

Requires Python 3.12+.

pip install treesearch-ud

# Optional: Install with visualization support (displaCy)
pip install treesearch-ud[viz]

From Source

Requires Python 3.12+ and Rust toolchain.

# Clone repository
git clone https://github.com/rmalouf/treesearch
cd treesearch

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install maturin
maturin develop

Quick Example

Find passive constructions in an English treebank:

import treesearch

# Parse a pattern for passive voice
pattern = treesearch.compile_query("""
    MATCH {
        V [upos="VERB"];
        Aux [lemma="be"];
        V -[aux:pass]-> Aux;
    }
""")

# Search a single file
for tree, match in treesearch.search("corpus.conllu", pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

Search multiple files with automatic parallel processing:

# Glob pattern for multiple files
for tree, match in treesearch.search("data/*.conllu", pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

# Or use the object-oriented API
treebank = treesearch.load("data/*.conllu")
for tree, match in treebank.search(pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

Pattern Language

Patterns specify structural constraints on dependency trees:

MATCH {
    Verb [upos="VERB" & lemma="help"];
    Obj [upos="NOUN"];
    Verb -[obj]-> Obj;
}

Node constraints: upos, xpos, lemma, form, deprel, feats.* (morphological features), misc.* (miscellaneous features)

Edge constraints: -> (child), -[label]-> (labeled edge), -/regex/-> (regex edge), !-> (negative), !-[label]-> (negative labeled), !-/regex/-> (negative regex)

Precedence: < (immediately precedes), << (precedes)

EXCEPT blocks: Reject matches where a condition is true (negative existential)

OPTIONAL blocks: Extend matches with additional bindings if possible

Data Format

Reads treebanks in CoNLL-U format. Supports plain text (.conllu), gzip-compressed (.conllu.gz), and zstd-compressed files (.conllu.zst) with automatic decompression.

Documentation

License

MIT

Citation

If you use Treesearch in your research, please cite:

@software{treesearch,
  author = {Malouf, Robert},
  title = {Treesearch: Pattern matching for dependency treebanks},
  year = {2025},
  url = {https://github.com/rmalouf/treesearch}
}

Project links

Data verified by PyPI on Aug 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rmalouf from gravatar.com rmalouf

Credits

Author: Rob Malouf

GitHub Statistics

Data verified by PyPI on Aug 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

viz

Tags

nlp linguistics dependency-parsing corpus-linguistics treebank

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

treesearch_ud-0.2.1.tar.gz (227.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

treesearch_ud-0.2.1-cp312-abi3-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.12+Windows x86-64

treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.2 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ x86-64

treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.6 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

treesearch_ud-0.2.1-cp312-abi3-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

treesearch_ud-0.2.1-cp312-abi3-macosx_10_12_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

Details for the file treesearch_ud-0.2.1.tar.gz.

File metadata

  • Download URL: treesearch_ud-0.2.1.tar.gz
  • Upload date:
  • Size: 227.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for treesearch_ud-0.2.1.tar.gz
Algorithm Hash digest
SHA256 4b0a3d98b5298d8afddb77bfe9a07d79ab5a32a28f57f04e097099b07a92337f
MD5 01aa636bd7e94a0208988df03bdd8510
BLAKE2b-256 bc2201001f21bc337d0fb4b6dd6347f5094331e56d280724b088418431ae0eb6

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1.tar.gz:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treesearch_ud-0.2.1-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for treesearch_ud-0.2.1-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 78e932eab4c8fbaba343a781d74606b2b7fab26572f4c5c6adc5d69e846d94ae
MD5 baf6f3dcda702cd78419d4c2df3018de
BLAKE2b-256 b7e7bd658de4f75bd9b089710ae0ca81b547be612af15c1c58f7bb1504883ebe

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1-cp312-abi3-win_amd64.whl:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2414dd305d5d929c16c45fba9107076ca0c4d9caa9260fc3a838ad719ba16d7e
MD5 43ff5e0a3c387d4cdd2836df5608a43f
BLAKE2b-256 61f82407e645c77c34c3491f4c023299cf75c4951e94d0e487c952a1b818993b

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 35b35efa9c2be36f23e5736a90fc20ebf2131d035bf2dbde7f902920f4053437
MD5 b844999ca532ee132df6968683c353a2
BLAKE2b-256 2bea3815e42b9169df31a019e633b727061e357f88e7f39a642f8572f8520d9d

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treesearch_ud-0.2.1-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for treesearch_ud-0.2.1-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ed0c530b84cdc43c776139b820b5c460762e6ec7c2a2f340d5d9143a84cb7f44
MD5 aa425c4ead2849aaef2212704be7c552
BLAKE2b-256 9191f269d6aa770dcb4b24b870803dd8d86f9af17c650630800488ac5df7d917

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treesearch_ud-0.2.1-cp312-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for treesearch_ud-0.2.1-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0c3caf20112d6c24cae5b3b4e37bfaaed7dbe8a1ab8ffdbbaefc2ae08fd1f44c
MD5 061cc67acd79866a0641d88802fbf67e
BLAKE2b-256 d624c4a63aed3a30d325eec580d1764d8e020bf083c46dca52752422d6b36993

See more details on using hashes here.

Provenance

The following attestation bundles were made for treesearch_ud-0.2.1-cp312-abi3-macosx_10_12_x86_64.whl:

Publisher: pypi.yml on rmalouf/treesearch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.1 This release

6 files

0.2.0

8 files

0.1.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page