{"id":21769937,"url":"https://github.com/mideind/binpackage","last_synced_at":"2026-05-15T02:30:42.839Z","repository":{"id":38196044,"uuid":"344877419","full_name":"mideind/BinPackage","owner":"mideind","description":"The vocabulary of modern Icelandic, encapsulated in a Python package.","archived":false,"fork":false,"pushed_at":"2025-10-22T22:06:42.000Z","size":13036,"stargazers_count":25,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-22T23:29:19.024Z","etag":null,"topics":["dictionary","icelandic","icelandic-inflection","icelandic-language","inflectional-morphology","nlp","python","python-package","python3","vocabulary"],"latest_commit_sha":null,"homepage":"https://mideind.is","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mideind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2021-03-05T17:00:51.000Z","updated_at":"2025-10-22T22:06:41.000Z","dependencies_parsed_at":"2023-11-15T10:38:44.190Z","dependency_job_id":"490add71-4346-45db-956b-2669e9b22fdd","html_url":"https://github.com/mideind/BinPackage","commit_stats":{"total_commits":131,"total_committers":7,"mean_commits":"18.714285714285715","dds":0.3587786259541985,"last_synced_commit":"47eda77187a3ea2f7e1a7c36d30bb4f928b4e63e"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/mideind/BinPackage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mideind%2FBinPackage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mideind%2FBinPackage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mideind%2FBinPackage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mideind%2FBinPackage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mideind","download_url":"https://codeload.github.com/mideind/BinPackage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mideind%2FBinPackage/sbom","scorecard":{"id":643750,"data":{"date":"2025-08-11","repo":{"name":"github.com/mideind/BinPackage","commit":"547a806de8e7bee0c2ce281e143838ebf524681b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4,"checks":[{"name":"Maintained","score":6,"reason":"8 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 1/12 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/python-package.yml:1","Warn: no topLevel permission defined: .github/workflows/wheels.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 21 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/python-package.yml:80: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/wheels.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/wheels.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/wheels.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/wheels.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/wheels.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/mideind/BinPackage/wheels.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/python-package.yml:52","Warn: pipCommand not pinned by hash: .github/workflows/wheels.yml:30","Warn: pipCommand not pinned by hash: .github/workflows/wheels.yml:45","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   3 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}}]},"last_synced_at":"2025-08-21T11:29:53.674Z","repository_id":38196044,"created_at":"2025-08-21T11:29:53.674Z","updated_at":"2025-08-21T11:29:53.674Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281731083,"owners_count":26551804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dictionary","icelandic","icelandic-inflection","icelandic-language","inflectional-morphology","nlp","python","python-package","python3","vocabulary"],"created_at":"2024-11-26T14:10:41.478Z","updated_at":"2026-05-15T02:30:42.824Z","avatar_url":"https://github.com/mideind.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub](https://img.shields.io/github/license/mideind/BinPackage)\n![Python 3.9+](https://img.shields.io/badge/python-3.9-blue.svg)\n![Release](https://shields.io/github/v/release/mideind/BinPackage?display_name=tag)\n![PyPI](https://img.shields.io/pypi/v/islenska)\n[![Python package](https://github.com/mideind/BinPackage/actions/workflows/python-package.yml/badge.svg)](https://github.com/mideind/BinPackage/actions/workflows/python-package.yml)\n\n# BinPackage\n\n**The Database of Icelandic Morphology (DIM, BÍN) encapsulated in a Python package**\n\n\u003cimg src=\"img/greynir-logo-large.png\" alt=\"Greynir\" width=\"200\" height=\"200\" align=\"right\" style=\"margin-left:20px; margin-bottom: 20px;\"\u003e\n\n*BinPackage* is a Python (\u003e= 3.9) package, published by\n[*Miðeind ehf*](https://mideind.is), that embeds the vocabulary of the\n[*Database of Icelandic Morphology*](https://bin.arnastofnun.is/DMII/)\n([*Beygingarlýsing íslensks nútímamáls*](https://bin.arnastofnun.is/), *BÍN*)\nand offers various lookups and queries of the data.\n\nThe database, maintained by\n[*The Árni Magnússon Institute for Icelandic Studies*](https://arnastofnun.is)\nand edited by chief editor *Kristín Bjarnadóttir*, contains over\n6.5 million entries, over 3.1 million unique word forms,\nand about 300,000 distinct lemmas.\n\nMiðeind has encapsulated the database in an easy-to-install Python package,\ncompressing it\nfrom a 400+ megabyte CSV file into an ~82 megabyte indexed binary structure.\nThe package maps this structure directly into memory (via `mmap`) for fast lookup.\nAn algorithm for handling compound words is an important additional feature\nof the package.\n\nWith BinPackage, `pip install islenska` is all you need to have almost all\nof the commonly used vocabulary of the modern Icelandic language at your\ndisposal via Python. Batteries are included; no additional databases,\ndownloads or middleware are required.\n\nBinPackage allows querying for word forms, as well as lemmas and grammatical variants.\nThis includes information about word classes/categories (noun, verb, ...),\ndomains (person names, place names, ...), inflectional tags and\nvarious annotations, such as degrees of linguistic acceptability and alternate\nspelling forms.\n\n## The basics of BÍN\n\nThe DMI/BÍN database is\n[published in electronic form](https://bin.arnastofnun.is/gogn/mimisbrunnur/)\nby [*The Árni Magnússon Institute for Icelandic Studies*](https://arnastofnun.is).\nThe database is\nreleased under the CC BY-SA 4.0 license, in CSV files having two main formats:\n*Sigrúnarsnið* (the *Basic Format*) and *Kristínarsnið* (the *Augmented Format*).\nSigrúnarsnið is more compact with six attributes\nfor each word form. Kristínarsnið is newer and more detailed,\nwith up to 15 attributes for each word form.\n\nBinPackage supports both formats, with the augmented format (represented\nby the class `Ksnid`) being returned from several functions\nand the basic format (represented by the named tuple `BinEntry`)\nfrom others, as documented below.\n\nFurther information in English about the word classes and the inflectional\ncategories in the DMI/BÍN database can be found\n[here](https://bin.arnastofnun.is/DMII/infl-system/).\n\n### The Basic Format\n\nThe BÍN *Basic Format* is represented in BinPackage with a Python `NamedTuple`\ncalled `BinEntry`, having the following attributes (further documented\n[here in Icelandic](https://bin.arnastofnun.is/gogn/SH-snid) and\n[here in English](https://bin.arnastofnun.is/DMII/LTdata/s-format/)):\n\n| Name     | Type  | Content  |\n|----------|-------|----------|\n| `ord` | `str` | Lemma (headword, *uppflettiorð*). |\n| `bin_id` | `int` | Identifier of the lemma, unique for a particular lemma/class combination. |\n| `ofl` | `str` | Word class/category, i.e. `kk`/`kvk`/`hk` for (masculine/feminine/neutral) nouns, `lo` for adjectives, `so` for verbs, `ao` for adverbs, etc.|\n| `hluti` | `str` | Semantic classification, i.e. `alm` for general vocabulary, `ism` for Icelandic person names, `örn` for place names (*örnefni*), etc.|\n| `bmynd` | `str` | Inflectional form (*beygingarmynd*). |\n| `mark` | `str` | Inflectional tag of this inflectional form, for instance `ÞGFETgr` for dative (*þágufall*, `ÞGF`), singular (*eintala*, `ET`), definite (*með greini*, `gr`). |\n\nThe inflectional tag in the `mark` attribute is documented in detail\n[here in Icelandic](https://bin.arnastofnun.is/gogn/greiningarstrengir/) and\n[here in English](https://bin.arnastofnun.is/DMII/LTdata/tagset/).\n\n### The Augmented Format\n\nThe BÍN *Augmented Format*, *Kristínarsnið*, is represented by instances of\nthe `Ksnid` class. It has the same six attributes as `BinEntry` (the Basic\nFormat) but adds nine attributes, shortly summarized below.\nFor details, please refer to the full documentation\n[in Icelandic](https://bin.arnastofnun.is/gogn/k-snid)\nor [in English](https://bin.arnastofnun.is/DMII/LTdata/k-format/).\n\n| Name     | Type  | Content  |\n|----------|-------|----------|\n| `einkunn` | `int` | Headword correctness grade, ranging from 0-5. |\n| `malsnid` | `str` | Genre/register indicator; e.g. `STAD` for dialectal, `GAM` for old-fashioned or `URE` for obsolete. |\n| `malfraedi` | `str` | Grammatical marking for further consideration, such as `STAFS` (spelling) or `TALA` (singular/plural). |\n| `millivisun` | `int` | Cross reference to the identifier (`bin_id` field) of a variant of this headword. |\n| `birting` | `str` | `K` for the DMII Core (*BÍN kjarni*) of most common and accepted word forms, `V` for other published BÍN entries. |\n| `beinkunn` | `int` | Correctness grade for this inflectional form, ranging from 0-5. |\n| `bmalsnid` | `str` | Genre/register indicator for this inflectional form. |\n| `bgildi` | `str` | Indicator for inflectional forms bound to idioms and other special cases. |\n| `aukafletta` | `str` | Alternative headword, e.g. plural form. |\n\n## Word compounding algorithm\n\nIcelandic allows almost unlimited creation of compound words. Examples are\n*síamskattarkjóll* (noun), *sólarolíulegur* (adjective), *öskurgrenja* (verb).\nIt is of course impossible for a static database to include all possible\ncompound words. To address this problem, BinPackage features a compound word\nrecognition algorithm, which is invoked when looking up any word that is not\nfound as-is in BÍN.\n\nThe algorithm relies on a list of valid word prefixes, stored in\n`src/islenska/resources/prefixes.txt`, and suffixes, stored in\n`src/islenska/resources/suffixes.txt`. These lists have been compressed\ninto data structures called *Directed Acyclic Word Graphs* (DAWGs). BinPackage\nuses these DAWGs to find optimal solutions for the compound word\nproblem, where an optimal solution is defined as the prefix+suffix\ncombination that has (1) the fewest prefixes and (2) the longest suffix.\n\nIf an optimal compound form exists for a word, its suffix is looked up in BÍN\nand used as an inflection template for the compound. *Síamskattarkjóll*\nis thus resolved into the prefix *síamskattar* and the suffix *kjóll*,\nwith the latter providing the inflection of *síamskattarkjóll* as\na singular masculine noun in the nominative case.\n\nThe compounding algorithm returns the prefixes and suffixes of the\noptimal compound in the `ord` and `bmynd` fields of the returned\n`BinEntry` / `Ksnid` instances, separated by hyphens `-`. As an example,\n*síamskattarkjóll* is returned as follows (note the hyphens):\n\n```python\n\u003e\u003e\u003e b.lookup(\"síamskattarkjóll\")\n('síamskattarkjóll', [\n    (ord='síamskattar-kjóll', kk/alm/0, bmynd='síamskattar-kjóll', NFET)\n])\n```\n\nLookups that are resolved via the compounding algorithm have a `bin_id` of zero.\nNote that the compounding algorithm will occasionally recognize nonexistent\nwords, for instance spelling errors, as compounds.\n\nIf desired, the compounding algorithm can be disabled\nvia an optional flag; see the documentation below.\n\n# Examples\n\n## Querying for word forms\n\n*Uppfletting beygingarmynda*\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e b.lookup(\"færi\")\n('færi', [\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-1P-ET),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-1P-FT),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-2P-ET),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-2P-FT),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-3P-ET),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-það-GM-VH-ÞT-3P-ET),\n    (ord='fara', so/alm/433568, bmynd='færi', OP-ÞGF-GM-VH-ÞT-3P-FT),\n    (ord='fara', so/alm/433568, bmynd='færi', GM-VH-ÞT-1P-ET),\n    (ord='fara', so/alm/433568, bmynd='færi', GM-VH-ÞT-3P-ET),\n    (ord='fær', lo/alm/448392, bmynd='færi', FVB-KK-NFET),\n    (ord='færa', so/alm/434742, bmynd='færi', GM-FH-NT-1P-ET),\n    (ord='færa', so/alm/434742, bmynd='færi', GM-VH-NT-1P-ET),\n    (ord='færa', so/alm/434742, bmynd='færi', GM-VH-NT-3P-ET),\n    (ord='færa', so/alm/434742, bmynd='færi', GM-VH-NT-3P-FT),\n    (ord='færi', hk/alm/1198, bmynd='færi', NFET),\n    (ord='færi', hk/alm/1198, bmynd='færi', ÞFET),\n    (ord='færi', hk/alm/1198, bmynd='færi', ÞGFET),\n    (ord='færi', hk/alm/1198, bmynd='færi', NFFT),\n    (ord='færi', hk/alm/1198, bmynd='færi', ÞFFT)\n])\n```\n\n`Bin.lookup()` returns the matched search key, usually identical to the\npassed-in word (here *færi*), and a list of matching entries\nin the basic format (*Sigrúnarsnið*), i.e. as instances of `BinEntry`.\n\nEach entry is a named tuple containing the\nlemma (`ord`), the word class, domain and id number (`hk/alm/1198`),\nthe inflectional form (`bmynd`) and tag (`GM-VH-NT-3P-FT`).\nThe tag strings are documented in detail\n[here in Icelandic](https://bin.arnastofnun.is/gogn/greiningarstrengir/) and\n[here in English](https://bin.arnastofnun.is/DMII/LTdata/tagset/).\n\n## Detailed word query\n\n*Uppfletting ítarlegra upplýsinga*\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e w, m = b.lookup_ksnid(\"allskonar\")\n\u003e\u003e\u003e # m is a list of 24 matching entries; we look at the first item only\n\u003e\u003e\u003e m[0].malfraedi\n'STAFS'\n\u003e\u003e\u003e m[0].einkunn\n4\n```\n\n`Bin.lookup_ksnid()` returns the matched search key and a list of all matching\nentries in the augmented format (*Kristínarsnið*). The fields of *Kristínarsnið*\nare documented in detail [here in Icelandic](https://bin.arnastofnun.is/gogn/k-snid)\nand [here in English](https://bin.arnastofnun.is/DMII/LTdata/k-format/).\n\nAs the example shows, the word `allskonar` is marked with the\ntag `STAFS` in the `malfraedi` field, and has an `einkunn` (correctness grade)\nof 4 (where 1 is the normal grade), giving a clue that this spelling is\nnonstandard. (A more correct form is `alls konar`, in two words.)\n\n## Lemmas and classes\n\n*Lemmur, uppflettiorð; orðflokkar*\n\nBinPackage can find all possible lemmas (headwords) of a word,\nand the classes/categories to which it may belong.\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e b.lookup_lemmas_and_cats(\"laga\")\n{('lag', 'hk'), ('lög', 'hk'), ('laga', 'so'), ('lagi', 'kk'), ('lögur', 'kk')}\n```\n\nHere we see, perhaps unexpectedly, that the word form *laga* has five possible lemmas:\nfour nouns (*lag*, *lög*, *lagi* and *lögur*, neutral (`hk`) and masculine (`kk`)\nrespectively), and one verb (`so`), having the infinitive (*nafnháttur*) *að laga*.\n\n## Lookup by BÍN identifier\n\nGiven a BÍN identifier (id number), BinPackage can return all entries for that id:\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e b.lookup_id(495410)\n[\u003cKsnid: bmynd='sko', ord/ofl/hluti/bin_id='sko'/uh/alm/495410, mark=OBEYGJANLEGT, ksnid='1;;;;K;1;;;'\u003e]\n```\n\n## Grammatical variants\n\nWith BinPackage, it is easy to obtain grammatical variants\n(alternative inflectional forms) of words: convert them between cases,\nsingular and plural, persons, degrees, moods, etc. Let's look\nat an example:\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e m = b.lookup_variants(\"Laugavegur\", \"kk\", \"ÞGF\")\n\u003e\u003e\u003e # m is a list of all possible variants of 'Laugavegur' in dative case.\n\u003e\u003e\u003e # In this particular example, m has only one entry.\n\u003e\u003e\u003e m[0].bmynd\n'Laugavegi'\n```\n\nThis is all it takes to convert the (masculine, `kk`) street name *Laugavegur*\nto dative case, commonly used in addresses.\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n\u003e\u003e\u003e m = b.lookup_variants(\"fallegur\", \"lo\", (\"EVB\", \"HK\", \"NF\", \"FT\"))\n\u003e\u003e\u003e # m contains a list of all inflectional forms that meet the given\n\u003e\u003e\u003e # criteria. In this example, we use the first form in the list.\n\u003e\u003e\u003e adj = m[0].bmynd\n\u003e\u003e\u003e f\"Ég sá {adj} norðurljósin\"\n'Ég sá fallegustu norðurljósin'\n```\n\nHere, we obtained the superlative degree, weak form (`EVB`, *efsta stig*,\n*veik beyging*), neutral gender (`HK`), nominative case (`NF`), plural (`FT`),\nof the adjective (`lo`) *fallegur* and used it in a sentence.\n\n# Documentation\n\n## `Bin()` constructor\n\nTo create an instance of the `Bin` class, do as follows:\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin()\n```\n\nYou can optionally specify the following boolean flags in the `Bin()`\nconstructor call:\n\n| Flag              | Default | Description                                    |\n|-------------------|---------|------------------------------------------------|\n| `add_negation`    | `True`    | For adjectives, find forms with the prefix `ó` even if only the non-prefixed version is present in BÍN. Example: find `ófíkinn` because `fíkinn` is in BÍN. |\n| `add_legur`       | `True`    | For adjectives, find all forms with an \"adjective-like\" suffix, i.e. `-legur`, `-leg`, etc. even if they are not present in BÍN. Example: `sólarolíulegt`. |\n| `add_compounds`   | `True`    | Find compound words that can be derived from BinPackage's collection of allowed prefixes and suffixes. The algorithm finds the compound word with the fewest components and the longest suffix. Example: `síamskattar-kjóll`. |\n| `replace_z`       | `True`    | Find words containing `tzt` and `z` by replacing these strings by `st` and `s`, respectively. Example: `veitzt` -\u003e `veist`. |\n| `only_bin`        | `False`   | Find only word forms that are originally present in BÍN, disabling all of the above described flags. |\n\nAs an example, to create a `Bin` instance that only returns word forms that occur\nin the original BÍN database, do like so:\n\n```python\n\u003e\u003e\u003e from islenska import Bin\n\u003e\u003e\u003e b = Bin(only_bin=True)\n```\n\n## `lookup()` function\n\nTo look up word forms and return summarized data in the Basic Format\n(`BinEntry` tuples), call the `lookup` function:\n\n```python\n\u003e\u003e\u003e w, m = b.lookup(\"mæla\")\n\u003e\u003e\u003e w\n'mæla'\n\u003e\u003e\u003e m\n[\n    (ord='mæla', kvk/alm/16302, bmynd='mæla', NFET),\n    (ord='mæla', kvk/alm/16302, bmynd='mæla', EFFT2),\n    (ord='mæla', so/alm/469211, bmynd='mæla', GM-NH),\n    (ord='mæla', so/alm/469211, bmynd='mæla', GM-FH-NT-3P-FT),\n    (ord='mæla', so/alm/469210, bmynd='mæla', GM-NH),\n    (ord='mæla', so/alm/469210, bmynd='mæla', GM-FH-NT-3P-FT),\n    (ord='mæli', hk/alm/2512, bmynd='mæla', EFFT),\n    (ord='mælir', kk/alm/4474, bmynd='mæla', ÞFFT),\n    (ord='mælir', kk/alm/4474, bmynd='mæla', EFFT)\n]\n```\n\nThis function returns a `Tuple[str, List[BinEntry]]` containing the string that\nwas actually used as a search key, and a list of `BinEntry` instances that\nmatch the search key. The list is empty if no matches were found, in which\ncase the word is probably not Icelandic or at least not spelled correctly.\n\nIn this example, however, the list has nine matching entries.\nWe see that the word form *mæla* is an inflectional form of five different\nheadwords (lemmas), including two verbs (`so`):\n(1) *mæla* meaning *to measure* (past tense *mældi*), and (2) *mæla* meaning *to speak*\n(past tense *mælti*). Other headwords are nouns, in all three genders:\nfeminine (`kvk`), neutral (`hk`) and masculine (`kk`).\n\nLet's try a different twist:\n\n```python\n\u003e\u003e\u003e w, m = b.lookup(\"síamskattarkjólanna\")\n\u003e\u003e\u003e w\n'síamskattarkjólanna'\n\u003e\u003e\u003e m\n[\n    (ord='síamskattar-kjóll', kk/alm/0, bmynd='síamskattar-kjólanna', EFFTgr)\n]\n```\n\nHere we see that *síamskattarkjólanna* is a compound word, amalgamated\nfrom *síamskattar* and *kjólanna*, with *kjóll* being the base lemma of the compound\nword. This is a masculine noun (`kk`), in the `alm` (general vocabulary) domain.\nNote that it has an id number (*bin_id*) equal to 0 since it is constructed\non-the-fly by BinPackage, rather than being found in BÍN. The grammatical\ntag string is `EFFTgr`, i.e. genitive (*eignarfall*, `EF`), plural (*fleirtala*,\n`FT`) and definite (*með greini*, `gr`).\n\nYou can specify the `at_sentence_start` option as being `True`, in which case\nBinPackage will also look for lower case words in BÍN even if the lookup word\nis upper case. As an example:\n\n```python\n\u003e\u003e\u003e _, m = b.lookup(\"Geysir\", at_sentence_start=True)\n\u003e\u003e\u003e m\n[\n    (ord='geysa', so/alm/483756, bmynd='geysir', GM-FH-NT-2P-ET),\n    (ord='geysa', so/alm/483756, bmynd='geysir', GM-FH-NT-3P-ET),\n    (ord='geysa', so/alm/483756, bmynd='geysir', GM-VH-NT-2P-ET),\n    (ord='Geysir', kk/bær/263617, bmynd='Geysir', NFET)\n]\n\u003e\u003e\u003e _, m = b.lookup(\"Geysir\", at_sentence_start=False)  # This is the default\n\u003e\u003e\u003e m\n[\n    (ord='Geysir', kk/bær/263617, bmynd='Geysir', NFET)\n]\n```\n\nAs you can see, the lowercase matches for *geysir* are returned as well\nas the single uppercase one, if `at_sentence_start` is set to `True`.\n\nAnother example:\n\n```python\n\u003e\u003e\u003e b.lookup(\"Heftaranum\", at_sentence_start=True)\n('heftaranum', [\n    (ord='heftari', kk/alm/7958, bmynd='heftaranum', ÞGFETgr)\n])\n```\n\nNote that here, the returned search key is `heftaranum` in lower case,\nsince `Heftaranum` in upper case was not found in BÍN.\n\nAnother option is `auto_uppercase`, which if set to `True`, causes the returned\nsearch key to be in upper case if any upper case entry exists in BÍN for the\nlookup word. This can be helpful when attempting to normalize\nall-lowercase input, for example from voice recognition systems. (Additional\ndisambiguation is typically still needed, since many common words and names do\nexist both in lower case and in upper case, and BinPackage cannot infer which\nform is desired in the output.)\n\nA final example of when the returned search key is different from the lookup word:\n\n```python\n\u003e\u003e\u003e\u003e b.lookup(\"þýzk\")\n('þýsk', [\n    (ord='þýskur', lo/alm/408914, bmynd='þýsk', FSB-KVK-NFET),\n    (ord='þýskur', lo/alm/408914, bmynd='þýsk', FSB-HK-NFFT),\n    (ord='þýskur', lo/alm/408914, bmynd='þýsk', FSB-HK-ÞFFT)\n])\n```\n\nHere, the input contains `z` or `tzt` which is translated to `s` or `st`\nrespectively to find a lookup match in BÍN. In this case, the actual matching\nword `þýsk` is returned as the search key instead of `þýzk`. (This behavior\ncan be disabled with the `replace_z` flag on the `Bin()` constructor,\nas described above.)\n\n`lookup()` has the following parameters:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to look up |\n| at_sentence_start | `bool` | `False` | `True` if BinPackage should also return lower case forms of the word, if it is given in upper case. |\n| auto_uppercase | `bool` | `False` | `True` if BinPackage should use and return upper case search keys, if the word exists in upper case. |\n\nThe function returns a `Tuple[str, List[BinEntry]]` instance.\nThe first element of the tuple is the search key that was matched in BÍN,\nand the second element is the list of matches, each represented\nby a `BinEntry` instance.\n\n## `lookup_ksnid()` function\n\nTo look up word forms and return full augmented format (*Kristínarsnið*)\nentries, call the `lookup_ksnid()` function:\n\n```python\n\u003e\u003e\u003e w, m = b.lookup_ksnid(\"allskonar\")\n\u003e\u003e\u003e w\n'allskonar'\n\u003e\u003e\u003e # m is a list of all matches of the word form; here we show the first item\n\u003e\u003e\u003e str(m[0])\n\"\u003cKsnid: bmynd='allskonar', ord/ofl/hluti/bin_id='allskonar'/lo/alm/175686, mark=FSB-KK-NFET, ksnid='4;;STAFS;496369;V;1;;;'\u003e\"\n\u003e\u003e\u003e m[0].malfraedi\n'STAFS'\n\u003e\u003e\u003e m[0].einkunn\n4\n\u003e\u003e\u003e m[0].millivisun\n496369\n```\n\nThis function is identical to `lookup()` except that it returns full\naugmented format entries of class `Ksnid`, with 15 attributes each, instead of\nbasic format (`BinEntry`) tuples. The same option flags are available\nand the logic for returning the search key is the same.\n\nThe example shows how the word *allskonar* has a grammatical comment\nregarding spelling (`m[0].malfraedi == 'STAFS'`) and a correctness grade\n(`m[0].einkunn`) of 4, as well as a cross-reference\nto the entry with id number (`bin_id`) 496369 - which is the lemma\n*alls konar*.\n\n`lookup_ksnid()` has the following parameters:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to look up |\n| at_sentence_start | `bool` | `False` | `True` if BinPackage should also return lower case forms of the word, if it is given in upper case. |\n| auto_uppercase | `bool` | `False` | `True` if BinPackage should use and return upper case search keys, if the word exists in upper case. |\n\nThe function returns a tuple of type `Tuple[str, List[Ksnid]]`.\nThe first element of the tuple is the search key that was matched in BÍN,\nand the second element is the list of matching entries, each represented\nby an instance of class `Ksnid`.\n\n## `lookup_id()` function\n\nIf you have a BÍN identifier (integer id) and need to look up the associated\naugmented format (*Kristínarsnið*) entries, call the `lookup_id()` function:\n\n```python\n\u003e\u003e\u003e b.lookup_id(495410)\n[\u003cKsnid: bmynd='sko', ord/ofl/hluti/bin_id='sko'/uh/alm/495410, mark=OBEYGJANLEGT, ksnid='1;;;;K;1;;;'\u003e]\n\n```\n\n`lookup_id()` has a single mandatory parameter:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| bin_id | `int` | | The BÍN identifier of the entries to look up. |\n\nThe function returns a list of type `List[Ksnid]`. If the given id number is not found\nin BÍN, an empty list is returned.\n\n## `lookup_cats()` function\n\nTo look up the possible classes/categories of a word (*orðflokkar*),\ncall the `lookup_cats` function:\n\n```python\n\u003e\u003e\u003e b.lookup_cats(\"laga\")\n{'so', 'hk', 'kk'}\n```\n\nThe function returns a `Set[str]` with all possible word classes/categories\nof the word form. If the word is not found in BÍN, or recognized using the\ncompounding algorithm, the function returns an empty set.\n\n`lookup_cats()` has the following parameters:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to look up |\n| at_sentence_start | `bool` | `False` | `True` if BinPackage should also include lower case forms of the word, if it is given in upper case. |\n\n## `lookup_lemmas_and_cats()` function\n\nTo look up the possible lemmas/headwords and classes/categories of a word\n(*lemmur og orðflokkar*), call the `lookup_lemmas_and_cats` function:\n\n```python\n\u003e\u003e\u003e b.lookup_lemmas_and_cats(\"laga\")\n{('lagi', 'kk'), ('lögur', 'kk'), ('laga', 'so'), ('lag', 'hk'), ('lög', 'hk')}\n```\n\nThe function returns a `Set[Tuple[str, str]]` where each tuple contains\na lemma/headword and a class/category, respectively.\nIf the word is not found in BÍN, or recognized using the\ncompounding algorithm, the function returns an empty set.\n\n`lookup_lemmas_and_cats()` has the following parameters:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to look up |\n| at_sentence_start | `bool` | `False` | `True` if BinPackage should also include lower case forms of the word, if it is given in upper case. |\n\n## `lookup_variants()` function\n\nThis function returns grammatical variants (particular inflectional forms)\nof a given word. For instance,\nit can return a noun in a different case, plural instead of singular,\nand/or with or without an attached definite article (*greinir*). It can return\nadjectives in different degrees (*frumstig*, *miðstig*, *efsta stig*), verbs\nin different persons or moods, etc.\n\nHere is a simple example, converting the masculine noun *heftaranum* from dative\nto nominative case (`NF`):\n\n```python\n\u003e\u003e\u003e m = b.lookup_variants(\"heftaranum\", \"kk\", \"NF\")\n\u003e\u003e\u003e m[0].bmynd\n'heftarinn'\n```\n\nHere we add a conversion to plural (`FT`) as well - note that we can pass multiple\ninflectional tags in a tuple:\n\n```python\n\u003e\u003e\u003e m = b.lookup_variants(\"heftaranum\", \"kk\", (\"NF\", \"FT\"))\n\u003e\u003e\u003e m[0].bmynd\n'heftararnir'\n```\n\nFinally, we specify a conversion to indefinite form (`nogr`):\n\n```python\n\u003e\u003e\u003e m = b.lookup_variants(\"heftaranum\", \"kk\", (\"NF\", \"FT\", \"nogr\"))\n\u003e\u003e\u003e m[0].bmynd\n'heftarar'\n```\n\nDefinite form is requested via `gr`, and indefinite form via `nogr`.\n\nTo see how `lookup_variants()` handles ambiguous word forms, let's\ntry our old friend *mæli* again:\n\n```python\n\u003e\u003e\u003e b.lookup_variants(\"mæli\", \"no\", \"NF\")\n[\n    \u003cKsnid: bmynd='mæli', ord/ofl/hluti/bin_id='mæli'/hk/alm/2512, mark=NFET, ksnid='1;;;;K;1;;;'\u003e,\n    \u003cKsnid: bmynd='mæli', ord/ofl/hluti/bin_id='mæli'/hk/alm/2512, mark=NFFT, ksnid='1;;;;K;1;;;'\u003e,\n    \u003cKsnid: bmynd='mælir', ord/ofl/hluti/bin_id='mælir'/kk/alm/4474, mark=NFET, ksnid='1;;;;K;1;;;'\u003e\n]\n```\n\nWe specified `no` (noun) as the word class constraint. The result thus contains\nnominative case forms of two nouns, one neutral (*mæli*, definite form *mælið*,\nwith identical singular `NFET` and plural `NFFT` form), and one\nmasculine (*mælir*, definite form *mælirinn*). If we had specified `hk` as the\nword class constraint, we would have gotten back the first two (neutral) entries only;\nfor `kk` we would have gotten back the third entry (masculine) only.\n\nLet's try modifying a verb from subjunctive (*viðtengingarháttur*)\n(e.g., *Ég/hún hraðlæsi bókina ef ég hefði tíma til þess*) to\nindicative mood (*framsöguháttur*), present tense\n(e.g. *Ég/hún hraðles bókina í flugferðinni*):\n\n```python\n\u003e\u003e\u003e m = b.lookup_variants(\"hraðlæsi\", \"so\", (\"FH\", \"NT\"))\n\u003e\u003e\u003e for mm in m: print(f\"{mm.ord} | {mm.bmynd} | {mm.mark}\")\nhraðlesa | hraðles | GM-FH-NT-1P-ET\nhraðlesa | hraðles | GM-FH-NT-3P-ET\n```\n\nWe get back both the 1st and the 3rd person inflection forms,\nsince they can both be derived from *hraðlæsi* and we don't constrain\nthe person in our variant specification. If only third person\nresults are desired, we could have specified `(\"FH\", \"NT\", \"3P\")` in the\nvariant tuple.\n\nFinally, let's describe this functionality in superlative terms:\n\n```python\n\u003e\u003e\u003e adj = b.lookup_variants(\"frábær\", \"lo\", (\"EVB\", \"KVK\"))[0].bmynd\n\u003e\u003e\u003e f\"Þetta er {adj} virknin af öllum\"\n'Þetta er frábærasta virknin af öllum'\n```\n\nNote how we ask for a superlative weak form (`EVB`) for a feminine subject (`KVK`),\ngetting back the adjective *frábærasta*. We could also ask for the\nstrong form (`ESB`), and then for the comparative (*miðstig*, `MST`):\n\n```python\n\u003e\u003e\u003e adj = b.lookup_variants(\"frábær\", \"lo\", (\"ESB\", \"KVK\", \"NF\", \"ET\"))[0].bmynd\n\u003e\u003e\u003e f\"Þessi virkni er {adj} af öllum\"\n'Þessi virkni er frábærust af öllum'\n\u003e\u003e\u003e adj = b.lookup_variants(\"frábær\", \"lo\", (\"MST\", \"KVK\"))[0].bmynd\n\u003e\u003e\u003e f\"Þessi virkni er {adj} en allt annað\"\n'Þessi virkni er frábærari en allt annað'\n```\n\nNote the explicit `\"NF\"` and `\"ET\"` tags in the `ESB` example: without\nthem, `lookup_variants()` may return e.g. an accusative or plural form\nfirst, since the input *frábær* is itself ambiguous between several\ncases and numbers. Adding the case/number tags pins the result.\n\nFinally, for some cool Python code for converting any adjective to\nthe superlative degree (*efsta stig*):\n\n```python\nfrom islenska import Bin\nb = Bin()\ndef efsta_stig(lo: str, kyn: str, veik_beyging: bool=True) -\u003e str:\n    \"\"\" Skilar efsta stigi lýsingarorðs, í umbeðnu kyni og beygingu \"\"\"\n    vlist = b.lookup_variants(lo, \"lo\", (kyn, \"EVB\" if veik_beyging else \"ESB\"))\n    return vlist[0].bmynd if vlist else \"\"\nprint(f\"Þetta er {efsta_stig('nýr', 'kvk')} framförin í íslenskri máltækni!\")\nprint(f\"Þetta er {efsta_stig('sniðugur', 'hk')} verkfærið!\")\n```\n\nThis will output:\n\n```\nÞetta er nýjasta framförin í íslenskri máltækni!\nÞetta er sniðugasta verkfærið!\n```\n\n`lookup_variants()` has the following parameters:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to use as a base for the lookup |\n| cat | `str` | | The word class, used to disambiguate the word. `no` (*nafnorð*) can be used to match any of `kk`, `kvk` and `hk`. |\n| to_inflection | `Union[str, Tuple[str, ...]]` | | One or more requested grammatical features, specified using fragments of the BÍN tag string. As a special case, `nogr` means indefinite form (no `gr`) for nouns. The parameter can be a single string or a tuple of several strings. |\n| lemma | `Optional[str]` | `None` | The lemma of the word, optionally used to further disambiguate it |\n| bin_id | `Optional[int]` | `None` | The id number of the word, optionally used to further disambiguate it |\n| inflection_filter | `Optional[Callable[[str], bool]]` | `None` | A callable taking a single string parameter and returning a `bool`. The `mark` attribute of a potential match will be passed to this function, and only included in the result if the function returns `True`. |\n\nThe function returns `List[Ksnid]`, i.e. a list of `Ksnid` instances that\nmatch the grammatical features requested in `to_inflection`. If no such\ninstances exist, an empty list is returned.\n\n## `lookup_lemmas()` function\n\nTo look up all entries having the given string as a lemma/headword,\ncall the `lookup_lemmas` function:\n\n```python\n\u003e\u003e\u003e b.lookup_lemmas(\"þyrla\")\n('þyrla', [\n    (ord='þyrla', kvk/alm/16445, bmynd='þyrla', NFET),  # Feminine noun\n    (ord='þyrla', so/alm/425096, bmynd='þyrla', GM-NH)  # Verb\n])\n\u003e\u003e\u003e b.lookup_lemmas(\"þyrlast\")\n('þyrlast', [\n    (ord='þyrla', so/alm/425096, bmynd='þyrlast', MM-NH)  # Middle voice infinitive\n])\n\u003e\u003e\u003e b.lookup_lemmas(\"þyrlan\")\n('þyrlan', [])\n```\n\nThe function returns a `Tuple[str, List[BinEntry]]` like `lookup()`,\nbut where the `BinEntry` list\nhas been filtered to include only lemmas/headwords. This is the reason why\n`b.lookup_lemmas(\"þyrlan\")` returns an empty list in the example above -\n*þyrlan* does not appear in BÍN as a lemma/headword.\n\nLemmas/headwords of verbs include the middle voice (*miðmynd*) of the\ninfinitive, `MM-NH`, as in the example for *þyrlast*.\n\n`lookup_lemmas()` has a single parameter:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| lemma | `str` | | The word to look up as a lemma/headword. |\n\n## `lookup_forms()` function\n\nReturn every inflectional form, in a particular case, of a given lemma.\nThis is the convenient way to enumerate all singular/plural and\ndefinite/indefinite forms of a noun (or all forms of any lemma) in one go.\n[`lookup_variants()`](#lookup_variants-function) is a more flexible\nalternative that supports more selective queries.\n\n```python\n\u003e\u003e\u003e b.lookup_forms(\"hestur\", \"kk\", \"ÞGF\")\n[\n    (ord='hestur', kk/alm/6179, bmynd='hestum', ÞGFFT),\n    (ord='hestur', kk/alm/6179, bmynd='hesti', ÞGFET),\n    (ord='hestur', kk/alm/6179, bmynd='hestinum', ÞGFETgr),\n    (ord='hestur', kk/alm/6179, bmynd='hestunum', ÞGFFTgr)\n]\n```\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| lemma | `str` | | The lemma/headword to enumerate forms for. |\n| cat | `str` | | The word category, e.g. `kk`, `kvk`, `hk`, `lo`, `so`. |\n| case | `str` | | The case to enumerate, one of `NF`, `ÞF`, `ÞGF`, `EF`. |\n\nThe function returns a `List[BinEntry]`. As with the other case-lookup\nfunctions below, the order of entries in the list is not guaranteed.\n\n## `lookup_nominative()`, `lookup_accusative()`, `lookup_dative()`, `lookup_genitive()`\n\nThese four functions return the inflectional forms of a word's lemma(s)\nin a particular case. They are useful when you already have an inflected\nword form and want to obtain other forms in a specific case. Unlike\n`lookup_forms()` they accept any surface form (not just the lemma) as\ninput and allow further filtering of the result.\n\n```python\n\u003e\u003e\u003e b.lookup_nominative(\"hestinum\", cat=\"kk\")\n[(ord='hestur', kk/alm/6179, bmynd='hesturinn', NFETgr)]\n\u003e\u003e\u003e b.lookup_nominative(\"hestinum\", cat=\"kk\", all_forms=True)\n[\n    (ord='hestur', kk/alm/6179, bmynd='hestur', NFET),\n    (ord='hestur', kk/alm/6179, bmynd='hesturinn', NFETgr),\n    (ord='hestur', kk/alm/6179, bmynd='hestar', NFFT),\n    (ord='hestur', kk/alm/6179, bmynd='hestarnir', NFFTgr)\n]\n```\n\nBy default, the returned forms inherit number (singular/plural) and\ndefiniteness from the input word — *hestinum* is dative singular\ndefinite, so only the matching nominative form (*hesturinn*) is returned.\nUse the keyword arguments below to override that behaviour.\n\nAll four functions share the same signature:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The inflected word form to look up. |\n| cat | `Optional[str]` | `None` | Restrict to a single category (`kk`, `kvk`, `hk`, `lo`, …); pass `no` to match any noun gender. |\n| lemma | `Optional[str]` | `None` | Restrict to entries whose lemma matches this string. |\n| bin_id | `Optional[int]` | `None` | Restrict to entries with this BÍN id. |\n| singular | `bool` | `False` | Force singular forms only. |\n| indefinite | `bool` | `False` | Force indefinite forms only (drop the `gr` definite article and weak adjective declensions). |\n| all_forms | `bool` | `False` | Return every form regardless of number/definiteness. Overrides `singular`, `indefinite`, and the number/definiteness of the input word. |\n| inflection_filter | `Optional[Callable[[str], bool]]` | `None` | Callable applied to each candidate's `mark` (beyging) string; entries are kept only when it returns `True`. |\n\nEach function returns `List[BinEntry]`. The order of entries within the\nreturned list is not guaranteed (results are derived from a `set`); the\nexample outputs above show one possible ordering.\n\n## `cast_to_accusative()`, `cast_to_dative()`, `cast_to_genitive()`\n\nCast a single word from nominative case into another case, returning the\ntarget inflectional form as a string. If the input word is not\ncase-inflectable (or BinPackage cannot resolve it) the input is returned\nunchanged.\n\n```python\n\u003e\u003e\u003e b.cast_to_accusative(\"maðurinn\")\n'manninn'\n\u003e\u003e\u003e b.cast_to_dative(\"maðurinn\")\n'manninum'\n\u003e\u003e\u003e b.cast_to_genitive(\"maðurinn\")\n'mannsins'\n\u003e\u003e\u003e b.cast_to_accusative(\"mennirnir\")\n'mennina'\n```\n\nThe casting is context-free: the functions only see one word at a time.\nThat means an ambiguous form may not be cast as intended in your\nsentence. To narrow the choice you can supply a `filter_func`.\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to cast (assumed to be in nominative case). |\n| filter_func | `Optional[Callable[[Iterable[BinEntry]], List[BinEntry]]]` | `None` | Optional callable receiving the list of candidate matches and returning a filtered subset. |\n\nEach function returns `str` — either the cast form, or the original word\nwhen no cast is possible.\n\n## `get_compound()` function\n\nLook up a word and, if it is recognised, return its decomposition into a\ncompound word built from BinPackage's prefix and suffix dictionaries.\nUnlike `lookup()`, this function never returns a non-compound interpretation\neven when one exists in BÍN, which is useful when you specifically want\nto inspect compound structure.\n\n```python\n\u003e\u003e\u003e w, m = b.get_compound(\"borgarstjórnarminnihlutinn\")\n\u003e\u003e\u003e w\n'borgarstjórnarminnihlutinn'\n\u003e\u003e\u003e m\n[(ord='borgarstjórnar-minnihluti', kk/alm/0, bmynd='borgarstjórnar-minnihlutinn', NFETgr)]\n```\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word to decompose. |\n| at_sentence_start | `bool` | `False` | `True` if BinPackage should also look for lower-case forms when the input is upper-case. |\n\nThe function returns `Tuple[str, List[BinEntry]]` — the resolved search\nkey and a list of compound `BinEntry` interpretations. The list is empty\nwhen no compound interpretation is found.\n\n## `contains()` function and the `in` operator\n\nTo test whether a word form is present in BÍN at all (without retrieving\nits entries), call `contains()`. The `in` operator on a `Bin` instance is\nequivalent.\n\n```python\n\u003e\u003e\u003e b.contains(\"hestur\")\nTrue\n\u003e\u003e\u003e \"hestur\" in b\nTrue\n\u003e\u003e\u003e \"xyzzy\" in b\nFalse\n```\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| w | `str` | | The word form to check. |\n\nReturns `bool`.\n\n## The `Orð` class\n\n`Orð` (\"word\") wraps a single word behind a stable, attribute-style API\nand supports producing arbitrary inflectional variants via Python's\n`format()` built-in. A singleton `Bin` instance is created on first use,\nso you don't need to manage one yourself.\n\n```python\n\u003e\u003e\u003e from islenska import Orð\n\u003e\u003e\u003e o = Orð(\"hestinum\")\n\u003e\u003e\u003e o.word        # the word as supplied\n'hestinum'\n\u003e\u003e\u003e o.key         # the BÍN search key actually matched\n'hestinum'\n\u003e\u003e\u003e o.ord         # the lemma/headword\n'hestur'\n\u003e\u003e\u003e o.ofl         # the word category\n'kk'\n\u003e\u003e\u003e o.bmynd       # the inflectional form\n'hestinum'\n\u003e\u003e\u003e o.mark        # the beyging (inflection tag)\n'ÞGFETgr'\n\u003e\u003e\u003e o.bin_id\n6179\n```\n\nThe constructor accepts:\n\n| Name | Type | Default | Description |\n|------|------|---------|-------------|\n| word | `str` | | The word to wrap. |\n| category | `Union[None, str, Iterable[str]]` | `None` | Optionally restrict matches to one or more word categories. Pass `\"no\"` to match any of `kk`, `kvk`, `hk`. |\n| at_sentence_start | `bool` | `False` | If `True`, also match lower-case forms when `word` is given in upper case. |\n\nAvailable properties:\n\n| Property | Description |\n|----------|-------------|\n| `word` | The word as passed to the constructor. |\n| `key` | The search key actually matched in BÍN (may differ from `word`). |\n| `entries` | `List[Ksnid]` of every entry matched by the constructor. |\n| `ord` | Lemma/headword. |\n| `ofl` | Word category (`kk`, `kvk`, `hk`, `lo`, `so`, …). |\n| `hluti` | Subcategory (`alm`, `ism`, `bær`, …). |\n| `bmynd` | The inflectional form. |\n| `mark` | The beyging string (empty if the word was not found in BÍN). |\n| `bin_id` | The BÍN identifier of the lemma (`0` if not found in BÍN). |\n\n`Orð` also implements `__format__`, so you can request a particular\ninflectional variant inline with an f-string. The format specifier is a\nhyphen- or underscore-separated list of BÍN tag fragments, in the same\nstyle accepted by `lookup_variants()`:\n\n```python\n\u003e\u003e\u003e o = Orð(\"maður\")\n\u003e\u003e\u003e f\"{o:ÞGF-FT-gr}\"\n'mönnunum'\n\u003e\u003e\u003e o = Orð(\"frábær\", category=\"lo\")\n\u003e\u003e\u003e f\"{o:EVB-KVK}\"\n'frábærasta'\n```\n\nThe casing of the formatted result follows the casing of the original\ninput word.\n\n# Implementation\n\nBinPackage is written in [Python 3](https://www.python.org/)\nand requires Python 3.9 or later. It runs on CPython 3.9+ and [PyPy](http://pypy.org/) 3.11.\n\nThe Python code calls a small C++ library to speed up lookup of word forms in the\ncompressed binary structure into which BÍN has been encoded.\nThis means that if a pre-compiled Python wheel is not\navailable on PyPI for your platform, you may need a set of development tools installed\non your machine, before you install BinPackage using `pip`:\n\n```bash\n# The following works on Debian/Ubuntu GNU/Linux\nsudo apt-get install python3-dev libffi-dev\n```\n\nBinPackage is fully type-annotated for use with Python static type checkers such\nas `mypy` and `Pylance` / `Pyright`.\n\n# Installation and setup\n\nYou must have Python \u003e= 3.9 installed on your machine (CPython 3.9+ or PyPy 3.11).\nIf you are using a Python virtual environment (`virtualenv`), activate it\nfirst (substituting your environment name for `venv` below):\n\n```bash\nvenv/bin/activate\n```\n\n...or, on Windows:\n\n```cmd\nC:\\\u003e venv\\scripts\\activate\n```\n\nThen, install BinPackage from the Python Package Index (PyPI),\nwhere the package is called `islenska`:\n\n```bash\npip install islenska\n```\n\nNow, you are ready to `import islenska` or `from islenska import Bin`\nin your Python code.\n\n----\n\nIf you want to install the package in editable source code mode,\ndo as follows:\n\n```bash\n# Clone the GitHub repository\ngit clone https://github.com/mideind/BinPackage\ncd BinPackage\n# Install the package in editable mode\npip install -e .  # Note the dot!\ncd src/islenska/resources\n# Fetch the newest BÍN data (KRISTINsnid.csv.zip)\n# (We remind you that the BÍN data is under the CC BY-SA 4.0 license; see below.)\nwget -O KRISTINsnid.csv.zip https://bin.arnastofnun.is/django/api/nidurhal/?file=KRISTINsnid.csv.zip\n# Unzip the data\nunzip -q KRISTINsnid.csv.zip\nrm KRISTINsnid.csv.*\ncd ../../..\n# Run the compressor to generate src/islenska/resources/compressed.bin\npython tools/binpack.py\n# Run the DAWG builder for the prefix and suffix files\npython tools/dawgbuilder.py\n# Now you're ready to go\n```\n\nThis will clone the GitHub repository into the BinPackage directory\nand install the package into your Python environment from the source files.\nThen, the newest BÍN data is fetched via `wget`\nfrom *Stofnun Árna Magnússonar* and compressed into a binary file.\nFinally, the Directed Acyclic Word Graph builder is run to\ncreate DAWGs for word prefixes and suffixes, used by the compound word\nalgorithm.\n\n## File details\n\nThe following files are located in the `src/islenska` directory within\nBinPackage:\n\n* `bindb.py`: The main `Bin` class; high-level interfaces into BinPackage.\n* `bincompress.py`: The lower-level `BinCompressed` class, interacting directly with\n  the compressed data in a binary buffer in memory.\n* `basics.py`: Basic data structures, such as the `BinEntry` NamedTuple.\n* `dawgdictionary.py`: Classes that handle compound words.\n* `bin.h`, `bin.cpp`: C++ code for fast lookup of word forms, called from Python via CFFI.\n* `tools/binpack.py`: A command-line tool that reads vocabulary data in .CSV\n  form and outputs a compressed binary file, `compressed.bin`.\n* `tools/dawgbuilder.py`: A command-line tool that reads information about word prefixes and suffixes\n  and creates corresponding directed acyclic word graph (DAWG) structures for\n  the word compounding logic.\n* `resources/prefixes.txt`, `resources/suffixes.txt`: Text files containing\n  valid Icelandic word prefixes and suffixes, respectively.\n\n# Copyright and licensing\n\nBinPackage embeds the vocabulary of the\n**[Database of Icelandic Morphology](https://bin.arnastofnun.is/DMII/)**\n(**[Beygingarlýsing íslensks nútímamáls](https://bin.arnastofnun.is/)**),\nabbreviated *BÍN*.\n\nThe copyright holder for BÍN is *The Árni Magnússon Institute*\n*for Icelandic Studies*. The BÍN data used herein are publicly available\nfor use under the terms of the\n[CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/legalcode),\nas further detailed\n[here in English](https://bin.arnastofnun.is/DMII/LTdata/conditions/) and\n[here in Icelandic](https://bin.arnastofnun.is/gogn/mimisbrunnur/).\n\nIn accordance with the BÍN license terms, credit is hereby given as follows:\n\n*Beygingarlýsing íslensks nútímamáls. Stofnun Árna Magnússonar í íslenskum fræðum.*\n*Höfundur og ritstjóri Kristín Bjarnadóttir.*\n\n----\n\n**Miðeind ehf., the publisher of BinPackage, claims no endorsement, sponsorship,**\n**or official status granted to it by the BÍN copyright holder.**\n\nBinPackage includes certain program logic, created by Miðeind ehf.,\nthat optionally exposes additions and modifications to the original\nBÍN source data. Such logic is enabled or disabled by user-settable flags,\nas described in the documentation above.\n\n----\n\nBinPackage is Copyright © 2025 [Miðeind ehf.](https://mideind.is)\nThe original author of this software is *Vilhjálmur Þorsteinsson*.\n\n\u003cimg src=\"img/MideindLogoVert400.png\" alt=\"Miðeind ehf.\"\n   width=\"118\" height=\"100\" align=\"left\"\n   style=\"margin-right:20px; margin-top: 10px; margin-bottom: 10px;\"\u003e\n\nThis software is licensed under the **MIT License**:\n\n*Permission is hereby granted, free of charge, to any person obtaining a*\n*copy of this software and associated documentation files (the \"Software\"),*\n*to deal in the Software without restriction, including without limitation*\n*the rights to use, copy, modify, merge, publish, distribute, sublicense,*\n*and/or sell copies of the Software, and to permit persons to whom the*\n*Software is furnished to do so, subject to the following conditions:*\n\n*The above copyright notice and this permission notice shall be included*\n*in all copies or substantial portions of the Software.*\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL\nTHE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nIf you would like to use this software in ways that are incompatible with the\nstandard MIT license, [contact Miðeind ehf.](mailto:mideind@mideind.is) to negotiate custom arrangements.\n\n# Acknowledgements\n\nParts of this software were developed under the auspices of the\nIcelandic Government's 5-year Language Technology Programme for Icelandic,\nmanaged by [Almannarómur](https://almannaromur.is). The LT Programme is described\n[here](https://www.stjornarradid.is/lisalib/getfile.aspx?itemid=56f6368e-54f0-11e7-941a-005056bc530c\u003e)\n(English version [here](https://clarin.is/media/uploads/mlt-en.pdf\u003e)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmideind%2Fbinpackage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmideind%2Fbinpackage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmideind%2Fbinpackage/lists"}