kwic 0.1.0__tar.gz

kwic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kwic-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: kwic
+Version: 0.1.0
+Summary: Key Word In Context
+Author: Eva
+Author-email: Eva <eva.evangelisti03@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: spacy>=3.8.15
+Requires-Dist: lemminflect>=0.2.3 ; extra == 'lemminflect'
+Requires-Dist: stanza>=1.14.0 ; extra == 'stanza'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/evaevangelisti/kwic
+Provides-Extra: lemminflect
+Provides-Extra: stanza
+Description-Content-Type: text/markdown
+
+# Key Word In Context
+
+Locates the lemmas of a query in the context that attests them.
+
+<!-- installation -->
+
+## Installation
+
+### Requirements
+
+- Python 3.12 or later
+
+### From PyPI
+
+```sh
+pip install kwic
+```
+
+A search reads with spaCy, whose pipelines are published apart from the library:
+
+```sh
+python -m spacy download en_core_web_sm
+```
+
+The other engines are extras:
+
+```sh
+pip install "kwic[stanza]"
+pip install "kwic[lemminflect]"
+```
+
+<!-- usage -->
+
+## Usage
+
+A search takes one context and the lemmas to look for.
+
+```python
+from kwic import Locator, POS, Query
+
+locator = Locator()
+
+locator.find("She found the keys she had lost.", [Query("find", POS.VERB)])
+# (Match(lemma='find', pos=POS.VERB, form='found', word_index=1, offsets=(4, 9)),)
+```
+
+### Query
+
+| Field | Default | |
+| --- | --- | --- |
+| `lemma` | | Dictionary form to look for, in whatever case |
+| `pos` | `None` | Tag a one-word occurrence must carry; a longer lemma is not narrowed |
+| `forms` | `()` | How else the lemma is written, taken where the engine read another |
+
+The engine cuts the lemma into words, and a space and a hyphen are one to it.
+
+```python
+locator.find("It was hunky-dory.", [Query("hunky dory")])
+# (Match(lemma='hunky dory', pos=POS.ADJ, form='hunky-dory', word_index=2, offsets=(7, 17)),)
+```
+
+A phrasal verb written apart runs from the verb to the particle.
+
+```python
+locator.find("She gave the money up.", [Query("give up")])
+# (Match(lemma='give up', pos=POS.VERB, form='gave the money up', word_index=1, offsets=(4, 21)),)
+```
+
+### Match
+
+| Field | |
+| --- | --- |
+| `lemma` | The lemma you asked for, as you wrote it |
+| `pos` | The tag it carries |
+| `form` | How it is written |
+| `word_index` | Where it opens among the words, from zero |
+| `offsets` | Where it falls in the text, half-open and in code points |
+
+### Contexts
+
+A context is a text, or the words it was split into. The second has no range.
+
+```python
+locator.find(("She", "found", "the", "keys"), [Query("find")])
+# (Match(lemma='find', pos=POS.VERB, form='found', word_index=1, offsets=None),)
+```
+
+### Many contexts
+
+`find_all` takes context and lemmas in pairs, and reads a batch at a time.
+
+```python
+for occurrences in locator.find_all(searches):
+    ...
+```
+
+### Engines
+
+An engine reads the context; the search reads the engine.
+
+```python
+from kwic.engines.stanza import StanzaEngine
+
+locator = Locator(StanzaEngine())
+```
+
+| Engine | Reads with | Install |
+| --- | --- | --- |
+| `SpacyEngine` | a spaCy pipeline, its English lemmatiser rules over the tag | `spacy` |
+| `StanzaEngine` | Stanza, a dictionary with a neural model behind it | `kwic[stanza]` |
+| `LemmInflectEngine` | spaCy for the tags, LemmInflect for the lemmas | `kwic[lemminflect]` |
+
+An extra is imported from the module wrapping it, so a package without it still loads.
+
+`SpacyEngine` takes the pipeline to load, `StanzaEngine` the language. Both parse unless told otherwise:
+
+| Parser | Buys | Costs |
+| --- | --- | --- |
+| spaCy | phrasal verbs apart, and several universal tags | a tenth of a reading |
+| Stanza | phrasal verbs apart | half its speed |
+
+```python
+Locator(SpacyEngine(parse=False))
+```
+
+<!-- accuracy -->
+
+## Accuracy
+
+English-EWT test section: 2,077 sentences, 417 lemmas, 3,619 occurrences.
+
+| Engine | Precision | Recall | F1 |
+| --- | --- | --- | --- |
+| `StanzaEngine` | 0.975 | 0.963 | 0.969 |
+| `SpacyEngine`, `en_core_web_trf` | 0.981 | 0.905 | 0.942 |
+| `SpacyEngine`, `en_core_web_lg` | 0.978 | 0.891 | 0.933 |
+| `SpacyEngine`, `en_core_web_sm` | 0.978 | 0.882 | 0.928 |
+| `LemmInflectEngine` | 0.976 | 0.872 | 0.921 |

kwic-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Key Word In Context
+
+Locates the lemmas of a query in the context that attests them.
+
+<!-- installation -->
+
+## Installation
+
+### Requirements
+
+- Python 3.12 or later
+
+### From PyPI
+
+```sh
+pip install kwic
+```
+
+A search reads with spaCy, whose pipelines are published apart from the library:
+
+```sh
+python -m spacy download en_core_web_sm
+```
+
+The other engines are extras:
+
+```sh
+pip install "kwic[stanza]"
+pip install "kwic[lemminflect]"
+```
+
+<!-- usage -->
+
+## Usage
+
+A search takes one context and the lemmas to look for.
+
+```python
+from kwic import Locator, POS, Query
+
+locator = Locator()
+
+locator.find("She found the keys she had lost.", [Query("find", POS.VERB)])
+# (Match(lemma='find', pos=POS.VERB, form='found', word_index=1, offsets=(4, 9)),)
+```
+
+### Query
+
+| Field | Default | |
+| --- | --- | --- |
+| `lemma` | | Dictionary form to look for, in whatever case |
+| `pos` | `None` | Tag a one-word occurrence must carry; a longer lemma is not narrowed |
+| `forms` | `()` | How else the lemma is written, taken where the engine read another |
+
+The engine cuts the lemma into words, and a space and a hyphen are one to it.
+
+```python
+locator.find("It was hunky-dory.", [Query("hunky dory")])
+# (Match(lemma='hunky dory', pos=POS.ADJ, form='hunky-dory', word_index=2, offsets=(7, 17)),)
+```
+
+A phrasal verb written apart runs from the verb to the particle.
+
+```python
+locator.find("She gave the money up.", [Query("give up")])
+# (Match(lemma='give up', pos=POS.VERB, form='gave the money up', word_index=1, offsets=(4, 21)),)
+```
+
+### Match
+
+| Field | |
+| --- | --- |
+| `lemma` | The lemma you asked for, as you wrote it |
+| `pos` | The tag it carries |
+| `form` | How it is written |
+| `word_index` | Where it opens among the words, from zero |
+| `offsets` | Where it falls in the text, half-open and in code points |
+
+### Contexts
+
+A context is a text, or the words it was split into. The second has no range.
+
+```python
+locator.find(("She", "found", "the", "keys"), [Query("find")])
+# (Match(lemma='find', pos=POS.VERB, form='found', word_index=1, offsets=None),)
+```
+
+### Many contexts
+
+`find_all` takes context and lemmas in pairs, and reads a batch at a time.
+
+```python
+for occurrences in locator.find_all(searches):
+    ...
+```
+
+### Engines
+
+An engine reads the context; the search reads the engine.
+
+```python
+from kwic.engines.stanza import StanzaEngine
+
+locator = Locator(StanzaEngine())
+```
+
+| Engine | Reads with | Install |
+| --- | --- | --- |
+| `SpacyEngine` | a spaCy pipeline, its English lemmatiser rules over the tag | `spacy` |
+| `StanzaEngine` | Stanza, a dictionary with a neural model behind it | `kwic[stanza]` |
+| `LemmInflectEngine` | spaCy for the tags, LemmInflect for the lemmas | `kwic[lemminflect]` |
+
+An extra is imported from the module wrapping it, so a package without it still loads.
+
+`SpacyEngine` takes the pipeline to load, `StanzaEngine` the language. Both parse unless told otherwise:
+
+| Parser | Buys | Costs |
+| --- | --- | --- |
+| spaCy | phrasal verbs apart, and several universal tags | a tenth of a reading |
+| Stanza | phrasal verbs apart | half its speed |
+
+```python
+Locator(SpacyEngine(parse=False))
+```
+
+<!-- accuracy -->
+
+## Accuracy
+
+English-EWT test section: 2,077 sentences, 417 lemmas, 3,619 occurrences.
+
+| Engine | Precision | Recall | F1 |
+| --- | --- | --- | --- |
+| `StanzaEngine` | 0.975 | 0.963 | 0.969 |
+| `SpacyEngine`, `en_core_web_trf` | 0.981 | 0.905 | 0.942 |
+| `SpacyEngine`, `en_core_web_lg` | 0.978 | 0.891 | 0.933 |
+| `SpacyEngine`, `en_core_web_sm` | 0.978 | 0.882 | 0.928 |
+| `LemmInflectEngine` | 0.976 | 0.872 | 0.921 |

kwic-0.1.0/pyproject.toml

@@ -0,0 +1,137 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "kwic"
+version = "0.1.0"
+description = "Key Word In Context"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["spacy>=3.8.15"]
+
+[[project.authors]]
+name = "Eva"
+email = "eva.evangelisti03@gmail.com"
+
+[project.optional-dependencies]
+lemminflect = ["lemminflect>=0.2.3"]
+stanza = ["stanza>=1.14.0"]
+
+[project.urls]
+Repository = "https://github.com/evaevangelisti/kwic"
+
+[dependency-groups]
+docs = [
+    "myst-parser>=5.1.0",
+    "shibuya>=2026.7.12",
+    "sphinx>=9.1.0",
+]
+lint = ["ruff>=0.16.2"]
+models = [
+    "en-core-web-lg",
+    "en-core-web-sm",
+    "en-core-web-trf",
+]
+test = [
+    "hypothesis>=6.165.9",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+]
+typing = ["basedpyright>=1.39.9"]
+
+[tool.uv.sources.en-core-web-sm]
+url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"
+
+[tool.uv.sources.en-core-web-lg]
+url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.8.0/en_core_web_lg-3.8.0-py3-none-any.whl"
+
+[tool.uv.sources.en-core-web-trf]
+url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_trf-3.8.0/en_core_web_trf-3.8.0-py3-none-any.whl"
+
+[tool.ruff]
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ANN",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "C90",
+    "D",
+    "DTZ",
+    "E",
+    "ERA",
+    "EXE",
+    "F",
+    "FBT",
+    "FLY",
+    "FURB",
+    "G",
+    "I",
+    "LOG",
+    "N",
+    "PERF",
+    "PGH",
+    "PIE",
+    "PLC",
+    "PLE",
+    "PLW",
+    "PT",
+    "PTH",
+    "PYI",
+    "RET",
+    "RSE",
+    "RUF",
+    "SIM",
+    "SLOT",
+    "T20",
+    "UP",
+    "W",
+    "YTT",
+]
+ignore = [
+    "D200",
+    "D212",
+    "PLC0415",
+]
+allowed-confusables = [
+    "–",
+    "’",
+    "‘",
+    "‐",
+    "‑",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 88
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+extraPaths = [
+    "tests",
+    "research",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--import-mode=importlib",
+    "--strict-markers",
+]
+markers = ["pipeline: exercises a search through a real pipeline"]
+pythonpath = ["tests"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true

kwic-0.1.0/pyproject.toml.orig

@@ -0,0 +1,143 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "kwic"
+version = "0.1.0"
+description = "Key Word In Context"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Eva", email = "eva.evangelisti03@gmail.com" }]
+dependencies = [
+    "spacy>=3.8.15",
+]
+
+[project.optional-dependencies]
+lemminflect = ["lemminflect>=0.2.3"]
+stanza = ["stanza>=1.14.0"]
+
+[project.urls]
+Repository = "https://github.com/evaevangelisti/kwic"
+
+[dependency-groups]
+docs = [
+    "myst-parser>=5.1.0",
+    "shibuya>=2026.7.12",
+    "sphinx>=9.1.0",
+]
+
+lint = [
+    "ruff>=0.16.2",
+]
+
+models = [
+    "en-core-web-lg",
+    "en-core-web-sm",
+    "en-core-web-trf",
+]
+
+test = [
+    "hypothesis>=6.165.9",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+]
+
+typing = [
+    "basedpyright>=1.39.9",
+]
+
+# The pipelines are published as wheels off their own releases rather than to
+# an index, so a lock file has to be told where each one is.
+[tool.uv.sources]
+en-core-web-sm = { url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl" }
+en-core-web-lg = { url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.8.0/en_core_web_lg-3.8.0-py3-none-any.whl" }
+en-core-web-trf = { url = "https://github.com/explosion/spacy-models/releases/download/en_core_web_trf-3.8.0/en_core_web_trf-3.8.0-py3-none-any.whl" }
+
+[tool.ruff]
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "A",     # flake8-builtins
+    "ANN",   # flake8-annotations
+    "ARG",   # flake8-unused-arguments
+    "ASYNC", # flake8-async
+    "B",     # flake8-bugbear
+    "BLE",   # flake8-blind-except
+    "C4",    # flake8-comprehensions
+    "C90",   # mccabe
+    "D",     # pydocstyle
+    "DTZ",   # flake8-datetimez
+    "E",     # pycodestyle, errors
+    "ERA",   # eradicate
+    "EXE",   # flake8-executable
+    "F",     # Pyflakes
+    "FBT",   # flake8-boolean-trap
+    "FLY",   # flynt
+    "FURB",  # refurb
+    "G",     # flake8-logging-format
+    "I",     # isort
+    "LOG",   # flake8-logging
+    "N",     # pep8-naming
+    "PERF",  # Perflint
+    "PGH",   # pygrep-hooks
+    "PIE",   # flake8-pie
+    "PLC",   # Pylint, conventions
+    "PLE",   # Pylint, errors
+    "PLW",   # Pylint, warnings
+    "PT",    # flake8-pytest-style
+    "PTH",   # flake8-use-pathlib
+    "PYI",   # flake8-pyi
+    "RET",   # flake8-return
+    "RSE",   # flake8-raise
+    "RUF",   # Ruff-specific rules
+    "SIM",   # flake8-simplify
+    "SLOT",  # flake8-slots
+    "T20",   # flake8-print
+    "UP",    # pyupgrade
+    "W",     # pycodestyle, warnings
+    "YTT",   # flake8-2020
+]
+
+ignore = [
+    "D200",    # A docstring is written across three lines, however short.
+    "D212",    # Its summary opens on the line below the quotes.
+    "PLC0415", # An engine imports what it wraps where it loads it, not before.
+]
+
+# A text sets its apostrophes and its hyphens typographically, which is what
+# the search unifies before it reads a lemma back out of one.
+allowed-confusables = ["–", "’", "‘", "‐", "‑"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 88
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+
+# Where the suite and the studies keep what they share, which pytest and the
+# scripts put on the path too.
+extraPaths = ["tests", "research"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib", "--strict-markers"]
+
+# A pipeline is loaded once and read by every property, which is slow enough
+# to be worth naming so that a run can leave it out.
+markers = ["pipeline: exercises a search through a real pipeline"]
+
+# The generators and the contexts the suite shares are written once, beside
+# the tests drawing from them.
+pythonpath = ["tests"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true

kwic-0.1.0/src/kwic/__init__.py

@@ -0,0 +1,19 @@
+"""
+Locating the lemmas of a query in the contexts that attest them.
+"""
+
+from .engines import Engine, SpacyEngine
+from .models import POS, Context, Match, Offsets, Query, Token
+from .search import Locator
+
+__all__ = [
+    "POS",
+    "Context",
+    "Engine",
+    "Locator",
+    "Match",
+    "Offsets",
+    "Query",
+    "SpacyEngine",
+    "Token",
+]

kwic-0.1.0/src/kwic/constants.py

@@ -0,0 +1,18 @@
+"""
+Values a search never varies.
+"""
+
+SPACY_PIPELINE = "en_core_web_sm"
+"""The spaCy pipeline loaded unless another is named. What the larger English
+pipelines add is vectors, which a search does not read."""
+
+STANZA_LANGUAGE = "en"
+"""The language Stanza loads its processors for unless another is named."""
+
+BATCH_SIZE = 256
+"""How many contexts a model reads at a time. Larger batches amortise the call
+into the model and hold more contexts in memory."""
+
+PROCESSES = 1
+"""How many processes a pipeline may run. More than one pays off over long
+runs alone, each having to load the model again."""

kwic-0.1.0/src/kwic/engines/__init__.py

@@ -0,0 +1,14 @@
+"""
+The analysers a search may read with.
+
+Only spaCy is loaded from here, it being the one dependency the package
+takes. The others are extras, imported from the module that wraps them.
+"""
+
+from .base import Engine
+from .spacy import SpacyEngine
+
+__all__ = [
+    "Engine",
+    "SpacyEngine",
+]