PySquashfsImage is a lightweight library and tool for reading and extracting
squashfs 4.0 little endian images in Python. It provides a high-level API for
easy access to these file systems. It is compatible with Python 2.7 and Python 3.1+.
## Installation
```
pip install PySquashfsImage
```
### Compression
Supported compression methods:
- Gzip
- [LZ4](https://pypi.org/project/lz4/) (requires Python 3.7+)
- [LZO](https://pypi.org/project/python-lzo/) (requires Python 2.7 or 3.5+, also see [here](https://test.pypi.org/project/python-lzo/))
- [XZ](https://pypi.org/project/backports.lzma/) (included in Python 3.3+)
- [Zstandard](https://pypi.org/project/zstandard/) (requires Python 3.7+)
Some of them require a third-party library that you'll need to install
separately if needed.
## Use as a library
### List all elements in the image:
```python
from PySquashfsImage import SquashFsImage
image = SquashFsImage.from_file('/path/to/my/image.img')
for item in image:
print(item.name)
image.close()
```
### Print all entries with their absolute path:
```python
from PySquashfsImage import SquashFsImage
# Use with a context manager (recommended).
with SquashFsImage.from_file('/path/to/my/image.img') as image:
for file in image:
print(file.path)
```
### Print all entries that aren't directories:
```python
from PySquashfsImage import SquashFsImage
with open('/path/to/my/image.img', "rb") as f:
imgbytes = f.read()
# Create an image from bytes.
with SquashFsImage.from_bytes(imgbytes) as image:
for item in image:
if not item.is_dir:
print(item.path)
```
### Save the content of a file:
```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_file
with SquashFsImage.from_file('/path/to/my/image.img') as image:
myfile = image.find('myfilename')
if myfile is not None:
with open('/tmp/' + myfile.name, 'wb') as f:
print('Saving original ' + myfile.path + ' in /tmp/' + myfile.name)
f.write(myfile.read_bytes())
# If the file is large it's preferable to iterate over its content.
hugefile = image.select("/hugedir/myhugefile.big")
with open("myhugefile.big", "wb") as f:
for block in hugefile.iter_bytes():
f.write(block)
# Or use extract_file(), which preserves the file's metadata (except extended attributes).
extract_file(myfile, "myextractedfile")
```
### Save the content of a directory:
```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_dir
with SquashFsImage.from_file('/path/to/my/image.img') as image:
mydir = image.select("/mydir")
if mydir is not None:
# Metadata is handled the same way as with extract_file().
extract_dir(mydir, "/tmp/mydir")
```
## Use as a command
### List
```
$ pysquashfs list -h
usage: pysquashfs list [-h] [-o OFFSET] [--utc] [--showtz] [-p PATH] [-r] [-t TYPE [TYPE ...]] file
List the contents of the file system
positional arguments:
file squashfs filesystem
optional arguments:
-h, --help show this help message and exit
-o OFFSET, --offset OFFSET absolute position of file system's start. Default: 0
--utc use UTC rather than local time zone when displaying time. Default: False
--showtz show UTC offset when displaying time. Default: False
-p PATH, --path PATH absolute path of directory or file to list. Default: '/'
-r, --recursive whether to list recursively. For the root directory the value is inverted. Default: False
-t TYPE [TYPE ...], --type TYPE [TYPE ...]
when listing a directory, filter by file type with f, d, l, p, s, b, c
```
Similar to `unsquashfs -ll -full`.
Example that only lists directories under the root directory:
```
$ pysquashfs list myimage.img -r -t d
drwxrwxrwx 1049/1049 468 2018-10-10 08:14:16 /bin
drwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /dev
drwxrwxrwx 1049/1049 869 2019-11-12 09:31:30 /etc
drwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /home
drwxrwxrwx 1049/1049 406 2017-12-11 08:14:16 /lib
drwxrwxrwx 1049/1049 98 2021-05-14 18:46:17 /mnt
drwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /proc
drwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /root
drwxrwxrwx 1049/1049 690 2021-05-14 12:11:44 /sbin
drwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /sys
drwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /tmp
drwxrwxrwx 1049/1049 364 2021-05-14 18:46:17 /usr
drwxrwxrwx 1049/1049 60 2018-11-09 05:38:43 /var
13 file(s) found
```
### Extract
```
$ pysquashfs extract -h
usage: pysquashfs extract [-h] [-o OFFSET] [-d DEST] [-p PATH] [-f] [-q] file
Extract files from the file system
positional arguments:
file squashfs filesystem
optional arguments:
-h, --help show this help message and exit
-o OFFSET, --offset OFFSET absolute position of file system's start. Default: 0
-d DEST, --dest DEST directory that will contain the extracted file(s). If it doesn't exist it will be created. Default: current directory
-p PATH, --path PATH absolute path of directory or file to extract. Default: '/'
-f, --force overwrite files that already exist. Default: False
-q, --quiet don't print extraction status. Default: False
```
On Unix, this command tries to give the same output as `unsquashfs`, but should
not be preferred over it. Some features like extended attributes are missing.
On Windows, you might create symlinks with a privileged account or with an
unprivileged one if Developer Mode is enabled.
Otherwise, a regular file containing the target will be created.
Special files are ignored.
Example command that will extract `/bin` under `/tmp`:
```
$ pysquashfs extract myimage.img -p /bin -d /tmp
```
### Scan
```
$ pysquashfs scan -h
usage: pysquashfs scan [-h] [--utc] [--showtz] file
Find and show all the superblocks that can be found in a file
positional arguments:
file squashfs filesystem
optional arguments:
-h, --help show this help message and exit
--utc use UTC rather than local time zone when displaying time. Default: False
--showtz show UTC offset when displaying time. Default: False
```
Output is similar to `unsquashfs -s [-UTC]`.
Example:
```
$ pysquashfs scan myimage.img
Superblock #1
Magic: 0x73717368
Major: 4
Minor: 0
Creation or last append time: 2018-06-16 16:46:23
Size: 7864320
Compression: XZ
Block size: 524288
Flags: 192
Number of fragments: 27
Number of inodes: 361
Number of ids: 1
Inode table start: 0x77E924
Directory table start: 0x77FAF2
Fragment table start: 0x781448
Lookup table start: 0x7817C6
ID table start: 0x7817D4
xattr ID table start: 0xFFFFFFFFFFFFFFFF
Offset: 161843
```
Raw data
{
"_id": null,
"home_page": "https://github.com/matteomattei/PySquashfsImage",
"name": "PySquashfsImage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*",
"maintainer_email": "",
"keywords": "filesystem,parser,squash,squashfs",
"author": "Matteo Mattei; Nicola Ponzeveroni;",
"author_email": "info@matteomattei.com",
"download_url": "https://files.pythonhosted.org/packages/62/b6/8a453795e78c743bb6d765b8288f86ecbba4e3522bcc1db534142062ec0e/PySquashfsImage-0.9.0.tar.gz",
"platform": null,
"description": "PySquashfsImage is a lightweight library and tool for reading and extracting\r\nsquashfs 4.0 little endian images in Python. It provides a high-level API for\r\neasy access to these file systems. It is compatible with Python 2.7 and Python 3.1+.\r\n\r\n## Installation\r\n\r\n```\r\npip install PySquashfsImage\r\n```\r\n\r\n### Compression\r\n\r\nSupported compression methods:\r\n\r\n- Gzip\r\n- [LZ4](https://pypi.org/project/lz4/) (requires Python 3.7+)\r\n- [LZO](https://pypi.org/project/python-lzo/) (requires Python 2.7 or 3.5+, also see [here](https://test.pypi.org/project/python-lzo/))\r\n- [XZ](https://pypi.org/project/backports.lzma/) (included in Python 3.3+)\r\n- [Zstandard](https://pypi.org/project/zstandard/) (requires Python 3.7+)\r\n\r\nSome of them require a third-party library that you'll need to install\r\nseparately if needed.\r\n\r\n## Use as a library\r\n\r\n### List all elements in the image:\r\n\r\n```python\r\nfrom PySquashfsImage import SquashFsImage\r\n\r\nimage = SquashFsImage.from_file('/path/to/my/image.img')\r\nfor item in image:\r\n print(item.name)\r\nimage.close()\r\n```\r\n\r\n### Print all entries with their absolute path:\r\n\r\n```python\r\nfrom PySquashfsImage import SquashFsImage\r\n\r\n# Use with a context manager (recommended).\r\nwith SquashFsImage.from_file('/path/to/my/image.img') as image:\r\n for file in image:\r\n print(file.path)\r\n```\r\n\r\n### Print all entries that aren't directories:\r\n\r\n```python\r\nfrom PySquashfsImage import SquashFsImage\r\n\r\nwith open('/path/to/my/image.img', \"rb\") as f:\r\n imgbytes = f.read()\r\n\r\n# Create an image from bytes.\r\nwith SquashFsImage.from_bytes(imgbytes) as image:\r\n for item in image:\r\n if not item.is_dir:\r\n print(item.path)\r\n```\r\n\r\n### Save the content of a file:\r\n\r\n```python\r\nfrom PySquashfsImage import SquashFsImage\r\nfrom PySquashfsImage.extract import extract_file\r\n\r\nwith SquashFsImage.from_file('/path/to/my/image.img') as image:\r\n myfile = image.find('myfilename')\r\n if myfile is not None:\r\n with open('/tmp/' + myfile.name, 'wb') as f:\r\n print('Saving original ' + myfile.path + ' in /tmp/' + myfile.name)\r\n f.write(myfile.read_bytes())\r\n\r\n # If the file is large it's preferable to iterate over its content.\r\n hugefile = image.select(\"/hugedir/myhugefile.big\")\r\n with open(\"myhugefile.big\", \"wb\") as f:\r\n for block in hugefile.iter_bytes():\r\n f.write(block)\r\n\r\n # Or use extract_file(), which preserves the file's metadata (except extended attributes).\r\n extract_file(myfile, \"myextractedfile\")\r\n```\r\n\r\n### Save the content of a directory:\r\n\r\n```python\r\nfrom PySquashfsImage import SquashFsImage\r\nfrom PySquashfsImage.extract import extract_dir\r\n\r\nwith SquashFsImage.from_file('/path/to/my/image.img') as image:\r\n mydir = image.select(\"/mydir\")\r\n if mydir is not None:\r\n # Metadata is handled the same way as with extract_file().\r\n extract_dir(mydir, \"/tmp/mydir\")\r\n```\r\n\r\n## Use as a command\r\n\r\n### List\r\n\r\n```\r\n$ pysquashfs list -h\r\nusage: pysquashfs list [-h] [-o OFFSET] [--utc] [--showtz] [-p PATH] [-r] [-t TYPE [TYPE ...]] file\r\n\r\nList the contents of the file system\r\n\r\npositional arguments:\r\n file squashfs filesystem\r\n\r\noptional arguments:\r\n -h, --help show this help message and exit\r\n -o OFFSET, --offset OFFSET absolute position of file system's start. Default: 0\r\n --utc use UTC rather than local time zone when displaying time. Default: False\r\n --showtz show UTC offset when displaying time. Default: False\r\n -p PATH, --path PATH absolute path of directory or file to list. Default: '/'\r\n -r, --recursive whether to list recursively. For the root directory the value is inverted. Default: False\r\n -t TYPE [TYPE ...], --type TYPE [TYPE ...]\r\n when listing a directory, filter by file type with f, d, l, p, s, b, c\r\n```\r\n\r\nSimilar to `unsquashfs -ll -full`.\r\n\r\nExample that only lists directories under the root directory:\r\n```\r\n$ pysquashfs list myimage.img -r -t d\r\ndrwxrwxrwx 1049/1049 468 2018-10-10 08:14:16 /bin\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /dev\r\ndrwxrwxrwx 1049/1049 869 2019-11-12 09:31:30 /etc\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /home\r\ndrwxrwxrwx 1049/1049 406 2017-12-11 08:14:16 /lib\r\ndrwxrwxrwx 1049/1049 98 2021-05-14 18:46:17 /mnt\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /proc\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /root\r\ndrwxrwxrwx 1049/1049 690 2021-05-14 12:11:44 /sbin\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 15:12:17 /sys\r\ndrwxrwxrwx 1049/1049 3 2021-05-14 18:46:17 /tmp\r\ndrwxrwxrwx 1049/1049 364 2021-05-14 18:46:17 /usr\r\ndrwxrwxrwx 1049/1049 60 2018-11-09 05:38:43 /var\r\n13 file(s) found\r\n```\r\n\r\n### Extract\r\n\r\n```\r\n$ pysquashfs extract -h\r\nusage: pysquashfs extract [-h] [-o OFFSET] [-d DEST] [-p PATH] [-f] [-q] file\r\n\r\nExtract files from the file system\r\n\r\npositional arguments:\r\n file squashfs filesystem\r\n\r\noptional arguments:\r\n -h, --help show this help message and exit\r\n -o OFFSET, --offset OFFSET absolute position of file system's start. Default: 0\r\n -d DEST, --dest DEST directory that will contain the extracted file(s). If it doesn't exist it will be created. Default: current directory\r\n -p PATH, --path PATH absolute path of directory or file to extract. Default: '/'\r\n -f, --force overwrite files that already exist. Default: False\r\n -q, --quiet don't print extraction status. Default: False\r\n```\r\n\r\nOn Unix, this command tries to give the same output as `unsquashfs`, but should\r\nnot be preferred over it. Some features like extended attributes are missing.\r\n\r\nOn Windows, you might create symlinks with a privileged account or with an\r\nunprivileged one if Developer Mode is enabled.\r\nOtherwise, a regular file containing the target will be created.\r\nSpecial files are ignored.\r\n\r\nExample command that will extract `/bin` under `/tmp`:\r\n```\r\n$ pysquashfs extract myimage.img -p /bin -d /tmp\r\n```\r\n\r\n### Scan\r\n\r\n```\r\n$ pysquashfs scan -h\r\nusage: pysquashfs scan [-h] [--utc] [--showtz] file\r\n\r\nFind and show all the superblocks that can be found in a file\r\n\r\npositional arguments:\r\n file squashfs filesystem\r\n\r\noptional arguments:\r\n -h, --help show this help message and exit\r\n --utc use UTC rather than local time zone when displaying time. Default: False\r\n --showtz show UTC offset when displaying time. Default: False\r\n```\r\n\r\nOutput is similar to `unsquashfs -s [-UTC]`.\r\n\r\nExample:\r\n```\r\n$ pysquashfs scan myimage.img\r\nSuperblock #1\r\nMagic: 0x73717368\r\nMajor: 4\r\nMinor: 0\r\nCreation or last append time: 2018-06-16 16:46:23\r\nSize: 7864320\r\nCompression: XZ\r\nBlock size: 524288\r\nFlags: 192\r\nNumber of fragments: 27\r\nNumber of inodes: 361\r\nNumber of ids: 1\r\nInode table start: 0x77E924\r\nDirectory table start: 0x77FAF2\r\nFragment table start: 0x781448\r\nLookup table start: 0x7817C6\r\nID table start: 0x7817D4\r\nxattr ID table start: 0xFFFFFFFFFFFFFFFF\r\nOffset: 161843\r\n```\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Squashfs image parser",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/matteomattei/PySquashfsImage"
},
"split_keywords": [
"filesystem",
"parser",
"squash",
"squashfs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28f7fa862ed72fbd05c930aeb979785fcfe33f9b874e639eb563f5ab9e46e277",
"md5": "0261956a4e24d818f1bf8605d58c0bd9",
"sha256": "a8ea154bf946f985c65fab7d8c08dc73da7ad47a0aebf0d13ae50ae56e369f90"
},
"downloads": -1,
"filename": "PySquashfsImage-0.9.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0261956a4e24d818f1bf8605d58c0bd9",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*",
"size": 43220,
"upload_time": "2023-07-02T23:41:09",
"upload_time_iso_8601": "2023-07-02T23:41:09.091363Z",
"url": "https://files.pythonhosted.org/packages/28/f7/fa862ed72fbd05c930aeb979785fcfe33f9b874e639eb563f5ab9e46e277/PySquashfsImage-0.9.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62b68a453795e78c743bb6d765b8288f86ecbba4e3522bcc1db534142062ec0e",
"md5": "a82dfa67cfbd8095cfc065bc99c846b0",
"sha256": "d3330ccd111ac2ef2cebf0c392077fe8608e2760862531d960ec9cb6c6d3655f"
},
"downloads": -1,
"filename": "PySquashfsImage-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "a82dfa67cfbd8095cfc065bc99c846b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*",
"size": 44190,
"upload_time": "2023-07-02T23:41:10",
"upload_time_iso_8601": "2023-07-02T23:41:10.785681Z",
"url": "https://files.pythonhosted.org/packages/62/b6/8a453795e78c743bb6d765b8288f86ecbba4e3522bcc1db534142062ec0e/PySquashfsImage-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-02 23:41:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matteomattei",
"github_project": "PySquashfsImage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysquashfsimage"
}
JSON
