# jsonl
[](https://github.com/rmoralespp/jsonl/actions?query=event%3Arelease+workflow%3ACI)
[](https://pypi.python.org/pypi/py-jsonl)
[](https://github.com/rmoralespp/jsonl)
[](https://app.codecov.io/gh/rmoralespp/jsonl)
[](https://github.com/rmoralespp/jsonl/blob/main/LICENSE)
[](https://github.com/charliermarsh/ruff)
[](https://pepy.tech/project/py-jsonl)
## About
**jsonl** is a lightweight Python library designed to simplify working with JSON Lines data, adhering to
the [JSON Lines format](https://jsonlines.org/).
### Features
- 🌎 Provides an API similar to Python's standard `json` module.
- 🚀 Supports custom (de)serialization via user-defined callbacks.
- 🗜️ Built-in support for `gzip`, `bzip2`, `xz` compression formats and `ZIP` or `TAR` archives.
- 🔧 Skips malformed lines during file loading.
- đź“Ą Loads from URLs, file paths, or file-like objects.
## Installation
To install **jsonl** using `pip`, run the following command:
```bash
pip install py-jsonl
```
## Getting Started
**Dumping data to a JSON Lines File**
Use `jsonl.dump` to incrementally write an iterable of dictionaries to a JSON Lines file:
```python
import jsonl
data = [
{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
{"name": "May", "wins": []},
]
jsonl.dump(data, "file.jsonl")
```
**Loading data from a JSON Lines source**
Use `jsonl.load` to incrementally load a JSON Lines source—such as a filename, URL, or file-like object—into as an iterator of dictionaries:
```python
import jsonl
# Load data from a JSON Lines file
iterator = jsonl.load("file.jsonl")
print(tuple(iterator))
# Load data from a URL
iterator = jsonl.load("https://example.com")
print(tuple(iterator))
```
**Dump multiple JSON Lines Files into an Archive (ZIP or TAR)**
Use `jsonl.dump_archive` to incrementally write structured data to multiple JSON Lines files,
which are then stored in a ZIP or TAR archive.
```python
import jsonl
data = [
# Create `file1.jsonl` withing the archive
("file1.jsonl", [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]),
# Create `file2.jsonl` within the archive
("path/to/file2.jsonl", [{"name": "Charlie", "age": 35}, {"name": "David", "age": 40}]),
# Append to `file1.jsonl` within the archive
("file1.jsonl", [{"name": "Eve", "age": 28}]),
]
jsonl.dump_archive("archive.zip", data)
```
**Load multiple JSON Lines Files from an Archive (ZIP or TAR)**
Use `jsonl.load_archive` to incrementally load multiple JSON Lines files from a ZIP or TAR archive.
This function allows you to filter files using Unix shell-style wildcards.
```python
import jsonl
# Load all JSON Lines files matching the pattern "*.jsonl" from the archive
for filename, iterator in jsonl.load_archive("archive.zip"):
print("Filename:", filename)
print("Data:", tuple(iterator))
```
**Dumping data to Multiple JSON Lines Files**
Use `jsonl.dump_fork` to incrementally write structured data to multiple JSON Lines files,
which can be useful when you want to separate data based on some criteria.
```python
import jsonl
data = [
# Create `file1.jsonl` or overwrite it if it exists
("file1.jsonl", [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]),
# Create `file2.jsonl` or overwrite it if it exists
("file2.jsonl", [{"name": "Charlie", "age": 35}, {"name": "David", "age": 40}]),
# Append to `file1.jsonl`
("file1.jsonl", [{"name": "Eve", "age": 28}]),
]
jsonl.dump_fork(data)
```
## Documentation
For more detailed information and usage examples, refer to the
project [documentation](https://rmoralespp.github.io/jsonl/)
## Development
To contribute to the project, you can run the following commands for testing and documentation:
First, ensure you have the latest version of `pip`:
```python -m pip install --upgrade pip```
### Running Unit Tests
Install the development dependencies and run the tests:
```
pip install --group=test # Install test dependencies
pytest tests/ # Run all tests
pytest --cov jsonl # Run tests with coverage
```
### Running Linter
```
pip install --group=lint # Install linter dependencies
ruff check . # Run linter
```
### Building the Documentation
To build the documentation locally, use the following commands:
```
pip install --group=doc # Install documentation dependencies
mkdocs serve # Start live-reloading docs server
mkdocs build # Build the documentation site
```
## License
This project is licensed under the [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "py-jsonl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jsonlines, ndjson, jsonl, json, gzip, bzip2, xz, zip, tar, utilities, serialization, deserialization",
"author": null,
"author_email": "rmoralespp <rmoralespp@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/42/bb/6c903a03d9d5c6a8b5d8a2638c11c900733e6e0707a36317cab516045637/py_jsonl-1.3.16.tar.gz",
"platform": null,
"description": "# jsonl\n\n[](https://github.com/rmoralespp/jsonl/actions?query=event%3Arelease+workflow%3ACI)\n[](https://pypi.python.org/pypi/py-jsonl)\n[](https://github.com/rmoralespp/jsonl)\n[](https://app.codecov.io/gh/rmoralespp/jsonl)\n[](https://github.com/rmoralespp/jsonl/blob/main/LICENSE)\n[](https://github.com/charliermarsh/ruff)\n[](https://pepy.tech/project/py-jsonl)\n\n## About\n\n**jsonl** is a lightweight Python library designed to simplify working with JSON Lines data, adhering to\nthe [JSON Lines format](https://jsonlines.org/).\n\n### Features\n\n- \ud83c\udf0e Provides an API similar to Python's standard `json` module.\n- \ud83d\ude80 Supports custom (de)serialization via user-defined callbacks.\n- \ud83d\udddc\ufe0f Built-in support for `gzip`, `bzip2`, `xz` compression formats and `ZIP` or `TAR` archives.\n- \ud83d\udd27 Skips malformed lines during file loading.\n- \ud83d\udce5 Loads from URLs, file paths, or file-like objects.\n\n## Installation\n\nTo install **jsonl** using `pip`, run the following command:\n\n```bash\npip install py-jsonl\n```\n\n## Getting Started\n\n**Dumping data to a JSON Lines File**\n\nUse `jsonl.dump` to incrementally write an iterable of dictionaries to a JSON Lines file:\n\n```python\nimport jsonl\n\ndata = [\n {\"name\": \"Gilbert\", \"wins\": [[\"straight\", \"7\u2663\"], [\"one pair\", \"10\u2665\"]]},\n {\"name\": \"May\", \"wins\": []},\n]\n\njsonl.dump(data, \"file.jsonl\")\n```\n\n**Loading data from a JSON Lines source**\n\nUse `jsonl.load` to incrementally load a JSON Lines source\u2014such as a filename, URL, or file-like object\u2014into as an iterator of dictionaries:\n\n```python\nimport jsonl\n\n# Load data from a JSON Lines file\niterator = jsonl.load(\"file.jsonl\")\nprint(tuple(iterator))\n\n# Load data from a URL\niterator = jsonl.load(\"https://example.com\")\nprint(tuple(iterator))\n```\n\n**Dump multiple JSON Lines Files into an Archive (ZIP or TAR)**\n\nUse `jsonl.dump_archive` to incrementally write structured data to multiple JSON Lines files, \nwhich are then stored in a ZIP or TAR archive.\n\n```python\nimport jsonl\n\ndata = [\n # Create `file1.jsonl` withing the archive\n (\"file1.jsonl\", [{\"name\": \"Alice\", \"age\": 30}, {\"name\": \"Bob\", \"age\": 25}]),\n # Create `file2.jsonl` within the archive\n (\"path/to/file2.jsonl\", [{\"name\": \"Charlie\", \"age\": 35}, {\"name\": \"David\", \"age\": 40}]),\n # Append to `file1.jsonl` within the archive\n (\"file1.jsonl\", [{\"name\": \"Eve\", \"age\": 28}]),\n]\njsonl.dump_archive(\"archive.zip\", data)\n```\n\n**Load multiple JSON Lines Files from an Archive (ZIP or TAR)**\n\nUse `jsonl.load_archive` to incrementally load multiple JSON Lines files from a ZIP or TAR archive. \nThis function allows you to filter files using Unix shell-style wildcards.\n\n```python\nimport jsonl\n\n# Load all JSON Lines files matching the pattern \"*.jsonl\" from the archive\nfor filename, iterator in jsonl.load_archive(\"archive.zip\"):\n print(\"Filename:\", filename)\n print(\"Data:\", tuple(iterator))\n```\n\n**Dumping data to Multiple JSON Lines Files**\n\nUse `jsonl.dump_fork` to incrementally write structured data to multiple JSON Lines files, \nwhich can be useful when you want to separate data based on some criteria.\n\n```python\nimport jsonl\n\ndata = [\n # Create `file1.jsonl` or overwrite it if it exists\n (\"file1.jsonl\", [{\"name\": \"Alice\", \"age\": 30}, {\"name\": \"Bob\", \"age\": 25}]),\n # Create `file2.jsonl` or overwrite it if it exists\n (\"file2.jsonl\", [{\"name\": \"Charlie\", \"age\": 35}, {\"name\": \"David\", \"age\": 40}]),\n # Append to `file1.jsonl`\n (\"file1.jsonl\", [{\"name\": \"Eve\", \"age\": 28}]),\n]\njsonl.dump_fork(data)\n```\n\n## Documentation\n\nFor more detailed information and usage examples, refer to the\nproject [documentation](https://rmoralespp.github.io/jsonl/)\n\n## Development\n\nTo contribute to the project, you can run the following commands for testing and documentation:\n\nFirst, ensure you have the latest version of `pip`:\n\n```python -m pip install --upgrade pip```\n\n### Running Unit Tests\n\nInstall the development dependencies and run the tests:\n\n```\npip install --group=test # Install test dependencies\npytest tests/ # Run all tests\npytest --cov jsonl # Run tests with coverage\n```\n\n### Running Linter\n\n```\npip install --group=lint # Install linter dependencies\nruff check . # Run linter\n```\n\n### Building the Documentation\n\nTo build the documentation locally, use the following commands:\n\n```\npip install --group=doc # Install documentation dependencies\nmkdocs serve # Start live-reloading docs server\nmkdocs build # Build the documentation site\n```\n\n## License\n\nThis project is licensed under the [MIT license](LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight Python library for handling jsonlines files.",
"version": "1.3.16",
"project_urls": {
"Changelog": "https://github.com/rmoralespp/jsonl/blob/main/CHANGELOG.md",
"Documentation": "https://rmoralespp.github.io/jsonl/",
"Homepage": "https://github.com/rmoralespp/jsonl",
"Issues": "https://github.com/rmoralespp/jsonl/issues",
"Source": "https://github.com/rmoralespp/jsonl"
},
"split_keywords": [
"jsonlines",
" ndjson",
" jsonl",
" json",
" gzip",
" bzip2",
" xz",
" zip",
" tar",
" utilities",
" serialization",
" deserialization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5ba6a4bb8d0b8ad26d583fb52b0a81ba90d85e37f9bd26067ffb9df2cc708ef8",
"md5": "0fe10e3213105b4ee9fe94a76a123761",
"sha256": "c86e92dfcbe4c44275758586ff457361d97dfc582acc3c626c3d8050e1e65cf1"
},
"downloads": -1,
"filename": "py_jsonl-1.3.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fe10e3213105b4ee9fe94a76a123761",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8479,
"upload_time": "2025-07-23T12:22:32",
"upload_time_iso_8601": "2025-07-23T12:22:32.585696Z",
"url": "https://files.pythonhosted.org/packages/5b/a6/a4bb8d0b8ad26d583fb52b0a81ba90d85e37f9bd26067ffb9df2cc708ef8/py_jsonl-1.3.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42bb6c903a03d9d5c6a8b5d8a2638c11c900733e6e0707a36317cab516045637",
"md5": "c496e161ada83849dba0f061e824dbb7",
"sha256": "1d7eb03a5bf2f0c632b9b9b7400ee0b33ac7cb86586ea713240daa3d82960bc1"
},
"downloads": -1,
"filename": "py_jsonl-1.3.16.tar.gz",
"has_sig": false,
"md5_digest": "c496e161ada83849dba0f061e824dbb7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13989,
"upload_time": "2025-07-23T12:22:33",
"upload_time_iso_8601": "2025-07-23T12:22:33.730570Z",
"url": "https://files.pythonhosted.org/packages/42/bb/6c903a03d9d5c6a8b5d8a2638c11c900733e6e0707a36317cab516045637/py_jsonl-1.3.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 12:22:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rmoralespp",
"github_project": "jsonl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "py-jsonl"
}
JSON
