asymgram 0.1.0__tar.gz

asymgram-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: asymgram
+Version: 0.1.0
+Summary: Utilities for CoNLL-U dependency tree objects, manipulation, evaluation, and error checking.
+Author-email: Tsy Yih <yihtsy@outlook.com>
+Project-URL: Homepage, https://github.com/Yihtsy/asymgram
+Project-URL: Repository, https://github.com/Yihtsy/asymgram
+Project-URL: Issues, https://github.com/Yihtsy/asymgram/issues
+Keywords: CoNLL-U,Universal Dependencies,dependency grammar,dependency parsing,corpus linguistics,treebank
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: conllu>=6.0
+Provides-Extra: nlp
+Requires-Dist: spacy>=3.0; extra == "nlp"
+Requires-Dist: spacy-stanza>=1.0; extra == "nlp"
+Requires-Dist: stanza>=1.0; extra == "nlp"
+
+# asymgram
+
+`asymgram` is a small Python toolkit for working with CoNLL-U dependency treebanks. It wraps parsed CoNLL-U tokens and sentences with convenient object references, provides tree manipulation helpers, evaluates dependency parses, and includes diagnostics for common annotation and format errors.
+
+The package is designed for corpus linguistics, dependency grammar research, Universal Dependencies style treebank work, and quick inspection of parser output.
+
+## Features
+
+- Enhanced CoNLL-U objects: `Token`, `TokenList`, `SentenceList`, and `SentenceLists`.
+- Context-aware token navigation, including head lookup, dependent lookup, subtree span extraction, and node depth.
+- Sentence and token manipulation helpers for merging tokens, splitting tokens, removing leaf nodes, merging sentences, and splitting sentences at marginal subtrees.
+- Basic dependency evaluation metrics: UAS and LAS.
+- CoNLL-U readers, writers, text reconstruction, and simple conversion helpers.
+- Error checking for common CoNLL-U and dependency treebank issues, including invalid IDs, malformed HEAD values, self-loops, cycles, missing roots, multiple roots, invalid UPOS/DEPREL labels, malformed FEATS/DEPS, punctuation mismatches, and suspicious UPOS-DEPREL combinations.
+
+## Installation
+
+```bash
+pip install asymgram
+```
+
+For local development:
+
+```bash
+git clone https://github.com/Yihtsy/asymgram.git
+cd asymgram
+pip install -e .
+```
+
+Optional NLP-related dependencies can be installed with:
+
+```bash
+pip install "asymgram[nlp]"
+```
+
+## Quick Start
+
+```python
+import asymgram as ag
+
+text = """
+# sent_id = demo-1
+# text = I saw her.
+1	I	_	PRON	_	_	2	nsubj	2:nsubj	_
+2	saw	_	VERB	_	_	0	root	0:root	_
+3	her	_	PRON	_	_	2	obj	2:obj	SpaceAfter=No
+4	.	_	PUNCT	_	_	2	punct	2:punct	_
+"""
+
+sentences = ag.parse(text)
+sentence = sentences[0]
+root = sentence.get_roottoken()
+
+print(root.form)
+print([tok.form for tok in root.get_deptokens(include_punct=True)])
+print(sentences.to_tokenized_text())
+```
+
+## Error Checking
+
+`asymgram.error_checker` can inspect raw CoNLL-U text, files, parsed sentences, or sentence lists.
+
+```python
+from asymgram.error_checker import check_conllu_text, check_file
+
+diagnostics = check_conllu_text(text)
+
+for diagnostic in diagnostics:
+    print(diagnostic.level, diagnostic.code, diagnostic.sent_id, diagnostic.token_id, diagnostic.message)
+
+file_diagnostics = check_file("treebank.conllu")
+```
+
+Each diagnostic is represented by a `Diagnostic` object:
+
+```python
+Diagnostic(
+    code="SELF_LOOP",
+    level="ERROR",
+    message="token cannot take itself as HEAD",
+    sent_id="demo-1",
+    token_id=3,
+)
+```
+
+Diagnostic levels are:
+
+- `ERROR`: structural or format problems that are usually automatically decidable.
+- `WARNING`: strong annotation warnings that should be manually checked.
+- `INFO`: low-frequency or linguistically atypical patterns that may still be valid.
+
+## Common APIs
+
+```python
+import asymgram as ag
+
+sentences = ag.read_conllu("sample.conllu")
+sentences.to_conllu("copy.conllu")
+
+root = sentences[0].get_roottoken()
+children = root.get_deptokens()
+span = root.get_subtree_span()
+
+uas = ag.uas(gold_sentences, predicted_sentences)
+las = ag.las(gold_sentences, predicted_sentences)
+```
+
+## Notes
+
+`asymgram` follows the CoNLL-U conventions used by Universal Dependencies, but it is not limited to official UD treebanks. Some diagnostics intentionally return warnings or info-level messages because many unusual UPOS-DEPREL combinations can be valid in ellipsis, multiword expressions, headless constructions, dates, measurements, names, and language-specific analyses.
+
+## License
+
+License information has not yet been specified.

asymgram-0.1.0/README.md

@@ -0,0 +1,114 @@
+# asymgram
+
+`asymgram` is a small Python toolkit for working with CoNLL-U dependency treebanks. It wraps parsed CoNLL-U tokens and sentences with convenient object references, provides tree manipulation helpers, evaluates dependency parses, and includes diagnostics for common annotation and format errors.
+
+The package is designed for corpus linguistics, dependency grammar research, Universal Dependencies style treebank work, and quick inspection of parser output.
+
+## Features
+
+- Enhanced CoNLL-U objects: `Token`, `TokenList`, `SentenceList`, and `SentenceLists`.
+- Context-aware token navigation, including head lookup, dependent lookup, subtree span extraction, and node depth.
+- Sentence and token manipulation helpers for merging tokens, splitting tokens, removing leaf nodes, merging sentences, and splitting sentences at marginal subtrees.
+- Basic dependency evaluation metrics: UAS and LAS.
+- CoNLL-U readers, writers, text reconstruction, and simple conversion helpers.
+- Error checking for common CoNLL-U and dependency treebank issues, including invalid IDs, malformed HEAD values, self-loops, cycles, missing roots, multiple roots, invalid UPOS/DEPREL labels, malformed FEATS/DEPS, punctuation mismatches, and suspicious UPOS-DEPREL combinations.
+
+## Installation
+
+```bash
+pip install asymgram
+```
+
+For local development:
+
+```bash
+git clone https://github.com/Yihtsy/asymgram.git
+cd asymgram
+pip install -e .
+```
+
+Optional NLP-related dependencies can be installed with:
+
+```bash
+pip install "asymgram[nlp]"
+```
+
+## Quick Start
+
+```python
+import asymgram as ag
+
+text = """
+# sent_id = demo-1
+# text = I saw her.
+1	I	_	PRON	_	_	2	nsubj	2:nsubj	_
+2	saw	_	VERB	_	_	0	root	0:root	_
+3	her	_	PRON	_	_	2	obj	2:obj	SpaceAfter=No
+4	.	_	PUNCT	_	_	2	punct	2:punct	_
+"""
+
+sentences = ag.parse(text)
+sentence = sentences[0]
+root = sentence.get_roottoken()
+
+print(root.form)
+print([tok.form for tok in root.get_deptokens(include_punct=True)])
+print(sentences.to_tokenized_text())
+```
+
+## Error Checking
+
+`asymgram.error_checker` can inspect raw CoNLL-U text, files, parsed sentences, or sentence lists.
+
+```python
+from asymgram.error_checker import check_conllu_text, check_file
+
+diagnostics = check_conllu_text(text)
+
+for diagnostic in diagnostics:
+    print(diagnostic.level, diagnostic.code, diagnostic.sent_id, diagnostic.token_id, diagnostic.message)
+
+file_diagnostics = check_file("treebank.conllu")
+```
+
+Each diagnostic is represented by a `Diagnostic` object:
+
+```python
+Diagnostic(
+    code="SELF_LOOP",
+    level="ERROR",
+    message="token cannot take itself as HEAD",
+    sent_id="demo-1",
+    token_id=3,
+)
+```
+
+Diagnostic levels are:
+
+- `ERROR`: structural or format problems that are usually automatically decidable.
+- `WARNING`: strong annotation warnings that should be manually checked.
+- `INFO`: low-frequency or linguistically atypical patterns that may still be valid.
+
+## Common APIs
+
+```python
+import asymgram as ag
+
+sentences = ag.read_conllu("sample.conllu")
+sentences.to_conllu("copy.conllu")
+
+root = sentences[0].get_roottoken()
+children = root.get_deptokens()
+span = root.get_subtree_span()
+
+uas = ag.uas(gold_sentences, predicted_sentences)
+las = ag.las(gold_sentences, predicted_sentences)
+```
+
+## Notes
+
+`asymgram` follows the CoNLL-U conventions used by Universal Dependencies, but it is not limited to official UD treebanks. Some diagnostics intentionally return warnings or info-level messages because many unusual UPOS-DEPREL combinations can be valid in ellipsis, multiword expressions, headless constructions, dates, measurements, names, and language-specific analyses.
+
+## License
+
+License information has not yet been specified.

asymgram-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asymgram"
+version = "0.1.0"
+description = "Utilities for CoNLL-U dependency tree objects, manipulation, evaluation, and error checking."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Tsy Yih", email = "yihtsy@outlook.com" }
+]
+keywords = [
+  "CoNLL-U",
+  "Universal Dependencies",
+  "dependency grammar",
+  "dependency parsing",
+  "corpus linguistics",
+  "treebank"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Topic :: Text Processing :: Linguistic"
+]
+dependencies = [
+  "conllu>=6.0"
+]
+
+[project.optional-dependencies]
+nlp = [
+  "spacy>=3.0",
+  "spacy-stanza>=1.0",
+  "stanza>=1.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/Yihtsy/asymgram"
+Repository = "https://github.com/Yihtsy/asymgram"
+Issues = "https://github.com/Yihtsy/asymgram/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+asymgram = ["sample/*.conllu"]

asymgram-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asymgram-0.1.0/src/asymgram/__init__.py

@@ -0,0 +1,56 @@
+__title__ = 'asymmetrencygrammar'
+__author__ = 'Tsy Yih'
+__email__ = 'yihtsy@outlook.com'
+__version__ = '0.1.0'
+
+from .format_changer import (
+    read_conllu,
+    write_conllu,
+    extract_all_deprels,
+    load_sentence_lists,
+    stanza_doc2conllu_style_text,
+    conllu_to_latex_standalone
+)
+
+from .conllu import (
+    Token,
+    TokenList,
+    SentenceList,
+    SentenceLists,
+    parse,
+    parse_incr,
+    to_sentencelist
+)
+
+from .tree_manipulation import (
+    merge_tokens,
+    split_token,
+    is_marginal_subtree,
+    merge_sentences,
+    remove_leaf_node,
+    split_sentence_at_node,
+    postprocess_stanza_depparse
+)
+
+from .metrics import (
+    uas,
+    las
+)
+
+from .error_checker import (
+    Diagnostic,
+    check_conllu_text,
+    check_file,
+    check_sentence,
+    check_sentence_list,
+    exists_error,
+    find_id_equals_head_errors
+)
+
+__all__ = [
+    "read_conllu", "write_conllu", "extract_all_deprels", "load_sentence_lists", "stanza_doc2conllu_style_text", "conllu_to_latex_standalone",
+    "Token", "TokenList", "SentenceList", "SentenceLists", "parse", "parse_incr", "to_sentencelist",
+    "merge_tokens", "split_token", "is_marginal_subtree", "merge_sentences", "remove_leaf_node", "split_sentence_at_node", "postprocess_stanza_depparse",
+    "uas", "las",
+    "Diagnostic", "check_conllu_text", "check_file", "check_sentence", "check_sentence_list", "exists_error", "find_id_equals_head_errors"
+]