{"id":21887043,"url":"https://github.com/knorrie/python-btrfs","last_synced_at":"2025-07-21T10:30:54.421Z","repository":{"id":9159849,"uuid":"61052438","full_name":"knorrie/python-btrfs","owner":"knorrie","description":"Python Btrfs module","archived":false,"fork":false,"pushed_at":"2024-09-21T13:49:26.000Z","size":780,"stargazers_count":112,"open_issues_count":12,"forks_count":22,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-31T07:50:08.370Z","etag":null,"topics":["btrfs","filesystem","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knorrie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":null,"license":"COPYING.LESSER","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}},"created_at":"2016-06-13T16:33:12.000Z","updated_at":"2024-10-25T11:02:04.000Z","dependencies_parsed_at":"2024-04-28T21:39:59.052Z","dependency_job_id":"91edbdc2-1a2e-4775-940a-82220c1d66d7","html_url":"https://github.com/knorrie/python-btrfs","commit_stats":{"total_commits":329,"total_committers":7,"mean_commits":47.0,"dds":0.3221884498480243,"last_synced_commit":"4aa37fc7f5b8133d30abf3ba398fa44d1b03c7ea"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knorrie%2Fpython-btrfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knorrie%2Fpython-btrfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knorrie%2Fpython-btrfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knorrie%2Fpython-btrfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knorrie","download_url":"https://codeload.github.com/knorrie/python-btrfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226903025,"owners_count":17700619,"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","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":["btrfs","filesystem","python"],"created_at":"2024-11-28T11:08:10.117Z","updated_at":"2024-11-28T11:08:14.608Z","avatar_url":"https://github.com/knorrie.png","language":"Python","funding_links":[],"categories":["BTRFS bindings"],"sub_categories":["[R-Linux](https://www.r-studio.com/free-linux-recovery)"],"readme":"python-btrfs\n============\n\n## What is python-btrfs?\n\npython-btrfs is a Python 3 library that provides ways to interact\nprogrammatically with an online btrfs file system.\n\nIt provides a pure python shadow implementation of data structures used in\nbtrfs together with convenient wrappers around the collection of kernel\nfunctions that are available in the btrfs kernel API.\n\nUsing them, we can examine the secret inner world of a btrfs file system for\neducational purposes.\n\n## Where do I get it?\n\nYour favourite GNU/Linux distro probably has it packaged as either python-btrfs\nor python3-btrfs package.\n\nThis git repository with source code can also directly be used with python 3.\nNo dependencies other than the python standard library are needed.\n\n## Should I be using this?\n\nThe target audience for using the library is system administrators and\ndevelopers who want to discover more about the internals of a btrfs file\nsystem, or want to create adjusted monitoring or administration tools that are\noptimized for their specific use cases.\n\nOf course, it's python, so, this is for who prefers programming python over\nprogramming C for quickly building fun stuff.\n\n## I have a broken file system, can I repair it using python-btrfs?\n\npython-btrfs does not directly access disk storage, it only uses functions\navailable in the kernel interface, using system calls. This also means that\npython-btrfs can not be used to repair a broken filesystem whenever the running\nLinux kernel cannot properly mount it.\n\n## What can I do with python-btrfs?\n\nUsing it allows one to take a peek behind the curtains of the regular\nfunctionality provided by the\n[btrfs-progs](https://github.com/kdave/btrfs-progs/blob/master/README.md)\nprograms and the\n[libbtrfsutil](https://github.com/kdave/btrfs-progs/blob/master/libbtrfsutil/README.md)\nC and Python library.\n\nYou can basically do anything that btrfs-progs or libbtrfsutil can do with an\nonline file system.  However, at the same time we're operating on a bit lower\nabstraction level. However again, that allows us to also be creative and make\noptimized utilities for our own special use cases.\n\nAn example is the `btrfs-balance-least-used` program that you can find in the\n`bin` directory. It's a modified algorithm for using btrfs balance to compact\nallocated space (i.e. defragment free space) as fast and efficient as possible\nby taking the usage ratio of the individual allocations of raw disk space into\naccount.\n\n## Show me some example code!\n\nLet's for example have a look at the equivalent of the `btrfs fi df /` command:\n\n```python3\n\u003e\u003e\u003e import btrfs\n\u003e\u003e\u003e with btrfs.FileSystem('/') as fs:\n...     for space in fs.space_info():\n...         print(space)\n... \nData, single: total=839.01GiB, used=838.47GiB\nSystem, DUP: total=8.00MiB, used=112.00KiB\nMetadata, DUP: total=4.00GiB, used=2.38GiB\nGlobalReserve, single: total=512.00MiB, used=0.00B\n```\n\nWell, that was easy! But, say, instead of this text, you want to create a pie\nchart out of it. Now, instead of writing a horrible program that parses back\nthe text output of the `btrfs fi df` command, we can access the values\ndirectly.\n\n```python3\n\u003e\u003e\u003e spaces = fs.space_info()\n\u003e\u003e\u003e len(spaces)\n4\n```\n\nThe `space_info()` function calls the `SPACE_INFO` kernel function, which returns\na list of `SpaceInfo` objects. By feeding one of those to the pretty printer in\nthe utils module, we can see all contents. The attributes are directly\naccessible in our code:\n\n```python3\n\u003e\u003e\u003e btrfs.utils.pretty_print(spaces[0])\n\u003cbtrfs.ioctl.SpaceInfo\u003e\nflags: Data, single\ntotal_bytes: 839.01GiB\nused_bytes: 838.50GiB\n\n\u003e\u003e\u003e spaces[0].flags\n1\n\u003e\u003e\u003e btrfs.utils.block_group_flags_str(spaces[0].flags)\n'DATA'\n\u003e\u003e\u003e spaces[0].total_bytes\n900877778944\n```\n\nSo, using these values, we could create a nice picture using an imaging library.\n\n## More examples!\n\nThe `bin` and `examples` directory in the source code contain an example\ncollection of programs that are built using the library.\n\n## Documentation\n\nReference documentation of the stable API of the library is written in Sphinx\nautodoc format. An [online version of the HTML\ndocumentation](https://python-btrfs.readthedocs.io/en/stable/genindex.html) is also\navailable.\n\nIn general, the\n[`btrfs.FileSystem`](https://python-btrfs.readthedocs.io/en/stable/btrfs.html#btrfs.ctree.FileSystem)\nobject, shown above, is the best starting point for exploring available\nfunctionality.\n\nTutorial style documentation will be added in the future.\n\n## License\n\nThe python-btrfs library itself is licensed under the LGPL-3.0.\n\nExample scripts in the bin directory are licensed under the MIT License\n(Expat). Feel free to use all the ideas and code from them to build new stuff using python-btrfs!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknorrie%2Fpython-btrfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknorrie%2Fpython-btrfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknorrie%2Fpython-btrfs/lists"}