[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81886":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":12,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":10,"rankLanguage":10,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},81886,"fastconstmap","lemire\u002Ffastconstmap","lemire","Fast, immutable, compact map from strings to 64-bit integers — for Python.","https:\u002F\u002Fpypi.org\u002Fproject\u002Ffastconstmap\u002F",null,"C",45,1,0,40.9,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:01:35","# fastconstmap\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg)](LICENSE)\n[![Test](https:\u002F\u002Fgithub.com\u002Flemire\u002Ffastconstmap\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Flemire\u002Ffastconstmap\u002Factions\u002Fworkflows\u002Ftest.yml)\n\nFast, immutable, compact map from strings to 64-bit integers — for Python.\n\n`fastconstmap` is a C implementation of the [binary fuse filter][bff]\nconstruction (a static perfect-hash-like structure), exposed to Python.\nGiven a `dict[str, int]` at build time, you get back a lookup object that:\n\n- uses **~9 bytes per key** (or ~18 with missing-key detection),\n- answers a lookup in **one xxhash call plus three array reads**,\n- is **immutable** and **serializable** to bytes \u002F a file,\n- exposes both a single-key API (`m[key]`) and a **batched** API\n  (`m.get_many([...])`) that amortises Python-C call overhead.\n\nThis package is a C port of the Go library\n[`github.com\u002Flemire\u002Fconstmap`][constmap]. It vendors\n[xxHash](https:\u002F\u002Fgithub.com\u002FCyan4973\u002FxxHash) (BSD-2) for string hashing.\n\n## Installation\n\n```\npip install fastconstmap\n```\n\nTo build from source you need a C compiler. There are no Python runtime\ndependencies.\n\n## Usage\n\n```python\nfrom fastconstmap import ConstMap, VerifiedConstMap\n\nd = {\"apple\": 100, \"banana\": 200, \"cherry\": 300}\n\n# Variant 1: minimal memory, no missing-key detection.\nm = ConstMap(d)\nm[\"apple\"]                  # -> 100\nm.get_many([\"banana\", \"cherry\"])  # -> [200, 300]\nm[\"grape\"]                  # undefined value!  use VerifiedConstMap if you care.\n\n# Variant 2: dict-like, detects keys not in the original mapping.\nvm = VerifiedConstMap(d)\nvm[\"apple\"]                 # -> 100\nvm.get(\"grape\")             # -> None\nvm.get(\"grape\", -1)         # -> -1\n\"grape\" in vm               # -> False\nvm[\"grape\"]                 # raises KeyError\nvm.get_many([\"banana\", \"grape\"], default=-1)  # -> [200, -1]\n\n# Either kind can be saved and loaded.\nm.save(\"mymap.cmap\")\nm2 = ConstMap.load(\"mymap.cmap\")\n\n# ... or as raw bytes.\nblob = m.to_bytes()\nm3 = ConstMap.from_bytes(blob)\n```\n\n### Choosing between `ConstMap` and `VerifiedConstMap`\n\n| | `ConstMap` | `VerifiedConstMap` |\n|--|--|--|\n| Bytes per key | ~9 | ~18 |\n| Lookup of present key | value | value |\n| Lookup of missing key | **undefined garbage** | `KeyError` \u002F `default` \u002F `None` |\n| Best if | you always look up known keys | you need dict-like semantics |\n\nThe false-positive rate of `VerifiedConstMap` (a missing key wrongly\nreported as present) is roughly 2⁻⁶⁴, which is negligible in practice.\n\n## Keys and values\n\n- **Keys** may be `str` or `bytes`. `str` is encoded as UTF-8 internally;\n  lookups must use the same encoding to match.\n- **Values** are 64-bit integers. We accept anything in\n  `[-2**63, 2**64 - 1]`; negatives are stored via two's complement, so\n  `m[k]` returns `2**64 - 1` for a value of `-1`. (To recover the signed\n  reading, reinterpret bits yourself.)\n\nKeys must be unique (Python dict semantics already guarantee this).\nConstruction raises `ValueError` in the extremely unlikely event of an\nxxhash collision (~2⁻⁶⁴ per key pair).\n\n## Sharing a map across processes (zero-copy)\n\nA map's serialized form *is* its in-memory lookup array (plus a small\nheader). That means it can live in a\n[`multiprocessing.shared_memory`](https:\u002F\u002Fdocs.python.org\u002F3\u002Flibrary\u002Fmultiprocessing.shared_memory.html)\nblock and be opened by any number of processes **without copying** — every\nprocess reads the same physical pages.\n\nThree methods make this work:\n\n| Method | Purpose |\n|--|--|\n| `m.serialized_size()` | bytes needed to hold the serialized map |\n| `m.write_into(buffer)` | serialize straight into a writable buffer (no intermediate `bytes`) |\n| `ConstMap.from_buffer(buffer)` | open a **zero-copy** map that reads directly from `buffer` |\n\nProducer — build once, publish into a **named** shared-memory block:\n\n```python\nfrom multiprocessing.shared_memory import SharedMemory\nfrom fastconstmap import ConstMap\n\nSHM_NAME = \"fastconstmap_demo\"\n\ncm = ConstMap({f\"key-{i}\": i for i in range(1_000_000)})\n\nshm = SharedMemory(create=True, size=cm.serialized_size(), name=SHM_NAME)\ncm.write_into(shm.buf)\n# keep `shm` alive (do not close\u002Funlink) while consumers are running\n```\n\nConsumer — attach to the same name with no copy:\n\n```python\nfrom multiprocessing.shared_memory import SharedMemory\nfrom fastconstmap import ConstMap\n\nSHM_NAME = \"fastconstmap_demo\"\n\nshm = SharedMemory(name=SHM_NAME)           # attach by name, no `create=`\ncm = ConstMap.from_buffer(shm.buf)          # zero-copy: no per-process copy\ncm[\"key-42\"]                                # reads straight from shared memory\n```\n\nChoosing the name yourself (rather than letting `SharedMemory` generate\none) means consumers can hard-code it or read it from config — no need to\npass the auto-generated name around. Pick a unique name; creating a block\nwhose name already exists raises `FileExistsError`.\n\nNotes and constraints:\n\n- **`from_buffer` does not copy.** The returned map holds a reference to the\n  buffer; the buffer (and, for shared memory, the `SharedMemory` object)\n  must stay alive and **must not be closed or mutated** while the map is in\n  use. Drop the map (`del cm`) before calling `shm.close()`.\n- The map is **immutable** — the intended pattern is *write once in the\n  producer, then only read in every process*. Concurrent readers need no\n  locking.\n- `from_buffer` verifies the magic bytes and the FNV-1a checksum, so a\n  truncated or corrupt block raises `ValueError` rather than returning\n  garbage.\n- Requirements: a **little-endian** host (x86-64, ARM64, …) and an\n  **8-byte-aligned** buffer. `SharedMemory.buf`, `bytes`, and `bytearray`\n  all satisfy the alignment requirement; an offset slice of a buffer may\n  not, in which case `from_buffer` raises `ValueError` — use\n  `from_bytes()` (which copies) instead.\n- `VerifiedConstMap` supports the same three methods.\n\n`from_bytes()` remains available when you *want* an owned copy (or need to\nload on a big-endian host): it copies the data and the resulting map owns\nits memory independently of the source buffer.\n\n## Benchmark\n\nOn an Apple M-series CPU, with 1,000,000 string keys\n(`key-{i}-{hex}` shaped strings):\n\n```\n=== fastconstmap benchmark — n = 1,000,000 keys, python 3.14.3 ===\n\nConstruction:\n  ConstMap.__init__                0.145 s\n  VerifiedConstMap.__init__        0.129 s\n  dict(d)                          0.005 s\n\nMemory:\n  ConstMap.nbytes                 9,043,968 bytes  (9.04 bytes\u002Fkey)\n  VerifiedConstMap.nbytes        18,087,936 bytes  (18.09 bytes\u002Fkey)\n  dict (table+keys+values)      118,380,958 bytes  (118.38 bytes\u002Fkey)\n  ratio dict \u002F ConstMap          13.1x\n\n\nSingle lookup, 2,000,000 ops:\n  dict[k]                         397.7 ns\u002Fop  (0.795 s total)\n  ConstMap[k]                     179.3 ns\u002Fop  (0.359 s total)\n  VerifiedConstMap[k]             213.2 ns\u002Fop  (0.426 s total)\n\nBatched lookup, 2000 × 1024:\n  dict comprehension               31.9 ns\u002Fop  (0.03 ms\u002Fbatch of 1024)\n  ConstMap.get_many                14.6 ns\u002Fop  (0.01 ms\u002Fbatch of 1024)\n  VerifiedConstMap.get_many        16.5 ns\u002Fop  (0.02 ms\u002Fbatch of 1024)\n\nSerialization:\n  ConstMap.to_bytes                0.009 s  (9,044,004 bytes)\n  ConstMap.from_bytes              0.009 s\n```\n\nFor better performance use `get_many` when you have an array of keys to look\nup at once.\n\nTo reproduce:\n\n```\npython benchmarks\u002Fbenchmark.py 1000000\n```\n\n## How it works\n\nGiven *n* (key, value) pairs the algorithm:\n\n1. Hashes each key with xxhash3 to a 64-bit value.\n2. Maps each hashed key to three positions `h0, h1, h2` in an array of\n   size ~1.125·*n*, using overlapping segments.\n3. Finds, via [peeling][bff], an ordering in which each key has an\n   exclusive cell among its three; walks that ordering in reverse,\n   setting each cell so `array[h0] ^ array[h1] ^ array[h2] == value`.\n\nLookup is one xxhash, three array reads, and two XORs.\n\nReferences:\n\n> Thomas Mueller Graf and Daniel Lemire,\n> [*Binary Fuse Filters: Fast and Smaller Than Xor Filters*][bff],\n> ACM Journal of Experimental Algorithmics, Vol. 27, 2022.\n> DOI: [10.1145\u002F3510449](https:\u002F\u002Fdoi.org\u002F10.1145\u002F3510449)\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n\n`fastconstmap` vendors xxHash, which is licensed under the BSD-2-clause\nlicense; see `src\u002Fthird_party\u002Fxxhash\u002FLICENSE`.\n\n[bff]:       https:\u002F\u002Farxiv.org\u002Fabs\u002F2201.01174\n[constmap]:  https:\u002F\u002Fgithub.com\u002Flemire\u002Fconstmap\n","`fastconstmap` 是一个用于 Python 的快速、不可变且紧凑的字符串到 64 位整数映射库。该库采用 C 语言实现，并通过二进制融合过滤器结构（一种静态完美哈希类似结构）提供高效的查找功能，每个键大约占用 9 字节（启用缺失键检测时为 18 字节），并且单次查找仅需一次 xxhash 调用加上三次数组读取。它支持序列化和反序列化，同时提供了批量查询接口以优化性能。适合需要高性能、内存使用效率高的场景，例如在大数据处理、缓存系统或任何需要频繁查询固定键值对的应用中。",2,"2026-06-11 04:07:05","CREATED_QUERY"]