diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..7f3c6db --- /dev/null +++ b/404.html @@ -0,0 +1,461 @@ + + + +
+ + + + + + + + + + + + + + + + + + +
ArchiveFile
+
+
+ArchiveFile(file: StrPath, mode: OpenArchiveMode = 'r', *, password: str | None = None, **kwargs: Any)
+
Open an archive file.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
file |
+
+ StrPath
+ |
+
+
+
+ Path to the archive file. This must be an existing file. + |
+ + required + | +
mode |
+
+ OpenArchiveMode
+ |
+
+
+
+ Specifies the mode for opening the archive file. Default is "r". + |
+
+ 'r'
+ |
+
password |
+
+ str | None
+ |
+
+
+
+ Password for encrypted archive files. Default is None. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Keyword arugments to pass to the underlying ZipFile/TarFile/RarFile/SevenZipFile handler. +Kwargs that are not relevent to the current handler will automatically +be removed so you don't have to worry about accidentally passing ZipFile's kwargs to TarFile. + |
+
+ {}
+ |
+
src/archivefile/_core.py
mode
+
+
+
+ property
+
+
+mode: OpenArchiveMode
+
Mode in which the archive file was opened
+
extract
+
+
+extract(member: StrPath | ArchiveMember, destination: StrPath = Path.cwd()) -> Path
+
Extract a member from the archive.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
member |
+
+ StrPath | ArchiveMember
+ |
+
+
+
+ Full name of the member to extract or an ArchiveMember object. + |
+ + required + | +
destination |
+
+ StrPath
+ |
+
+
+
+ The path to the directory where the member will be extracted. +If not specified, the current working directory is used as the default destination. + |
+
+ cwd()
+ |
+
Returns:
+Type | +Description | +
---|---|
+ Path
+ |
+
+
+
+ The path to the extracted file. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.zip") as archive:
+ file = archive.extract("hello-world/pyproject.toml")
+ file.read_text()
+ # [tool.poetry]
+ # name = "hello-world"
+ # version = "0.1.0"
+ # description = ""
+ # readme = "README.md"
+ # packages = [{include = "hello_world", from = "src"}]
+
src/archivefile/_core.py
345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 |
|
extractall
+
+
+extractall(destination: StrPath = Path.cwd(), members: Iterable[StrPath | ArchiveMember] | None = None) -> Path
+
Extract all members of the archive to destination directory.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
destination |
+
+ StrPath
+ |
+
+
+
+ The path to the directory where the members will be extracted to. +If not specified, the current working directory is used as the default destination. + |
+
+ cwd()
+ |
+
members |
+
+ Iterable[StrPath | ArchiveMember] | None
+ |
+
+
+
+ Iterable of member names or ArchiveMember objects to extract. +Default is None which will extract all members. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ Path
+ |
+
+
+
+ The path to the destination directory. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.zip") as archive:
+ outdir = archive.extractall()
+
+for file in outdir.rglob("*"):
+ print(file)
+ # /source/hello-world
+ # /source/hello-world/pyproject.toml
+ # /source/hello-world/README.md
+ # /source/hello-world/src
+ # /source/hello-world/tests
+ # /source/hello-world/src/hello_world
+ # /source/hello-world/src/hello_world/__init__.py
+ # /source/hello-world/tests/__init__.py
+
src/archivefile/_core.py
409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 |
|
get_member
+
+
+get_member(member: StrPath) -> ArchiveMember
+
Get the ArchiveMember object for the member by it's name.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
member |
+
+ StrPath
+ |
+
+
+
+ Name or path of the member as present in the archive. + |
+ + required + | +
Returns:
+Type | +Description | +
---|---|
+ ArchiveMember
+ |
+
+
+
+ Represents a member of the archive. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.tar") as archive:
+ archive.get_member("README.md")
+ # ArchiveMember(name='README.md', size=3799, compressed_size=3799, datetime=datetime.datetime(2024, 4, 10, 20, 10, 57, tzinfo=datetime.timezone.utc), checksum=5251, is_dir=False, is_file=True)
+
src/archivefile/_core.py
141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 |
|
get_members
+
+
+get_members() -> tuple[ArchiveMember, ...]
+
Retrieve all members from the archive as a tuple of ArchiveMember objects.
+ + + +Returns:
+Type | +Description | +
---|---|
+ tuple[ArchiveMember, ...]
+ |
+
+
+
+ Members of the archive as a tuple of ArchiveMember objects. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.tar") as archive:
+ archive.get_members()
+ # (
+ # ArchiveMember(name="project/pyproject.toml", size=1920, compressed_size=1920, datetime=datetime.datetime(2024, 4, 10, 20, 10, 57, tzinfo=datetime.timezone.utc), checksum=6038, is_dir=False, is_file=True),
+ # ArchiveMember(name="project/src", size=0, compressed_size=0, datetime=datetime.datetime(2024, 4, 10, 20, 10, 57, tzinfo=datetime.timezone.utc), checksum=4927, is_dir=True, is_file=False),
+ # )
+
src/archivefile/_core.py
get_names
+
+
+Retrieve names of all members in the archive as a tuple of strings.
+ + + +Returns:
+Type | +Description | +
---|---|
+ tuple[str, ...]
+ |
+
+
+
+ Members of the archive as a tuple of strings. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.tar") as archive:
+ archive.get_names()
+ # (
+ # "project/pyproject.toml",
+ # "project/src",
+ # )
+
src/archivefile/_core.py
read_bytes
+
+
+read_bytes(member: StrPath | ArchiveMember) -> bytes
+
Read the member in bytes mode.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
member |
+
+ StrPath | ArchiveMember
+ |
+
+
+
+ Name or path of the member as present in the archive or an ArchiveMember object. + |
+ + required + | +
Returns:
+Type | +Description | +
---|---|
+ bytes
+ |
+
+
+
+ The contents of the file as bytes. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.zip") as archive:
+ archive.read_bytes("hello-world/pyproject.toml")
+ # b'[tool.poetry]\r\nname = "hello-world"\r\nversion = "0.1.0"\r\ndescription = ""\r\nreadme = "README.md"\r\npackages = [{include = "hello_world", from = "src"}]\r\n'
+
src/archivefile/_core.py
read_text
+
+
+read_text(member: StrPath | ArchiveMember, encoding: str | None = 'utf-8', errors: Literal['strict', 'ignore', 'replace', 'backslashreplace', 'surrogateescape', 'xmlcharrefreplace', 'namereplace'] | None = None) -> str
+
Read the member in text mode.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
member |
+
+ StrPath | ArchiveMember
+ |
+
+
+
+ Name or path of the member as present in the archive or an ArchiveMember object. + |
+ + required + | +
encoding |
+
+ str | None
+ |
+
+
+
+ Encoding used to read the file. Default is |
+
+ 'utf-8'
+ |
+
errors |
+
+ Literal['strict', 'ignore', 'replace', 'backslashreplace', 'surrogateescape', 'xmlcharrefreplace', 'namereplace'] | None
+ |
+
+
+
+ String that specifies how encoding and decoding errors are to be handled. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ str
+ |
+
+
+
+ The contents of the file as a string. + |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.zip") as archive:
+ archive.read_text("hello-world/pyproject.toml")
+ # [tool.poetry]
+ # name = "hello-world"
+ # version = "0.1.0"
+ # description = ""
+ # readme = "README.md"
+ # packages = [{include = "hello_world", from = "src"}]
+
src/archivefile/_core.py
tree
+
+
+tree(max_depth: int = 0, style: Literal['ansi', 'ascii', 'const', 'const_bold', 'rounded', 'double'] = 'const') -> None
+
Print the contents of the archive as a tree.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
max_depth |
+
+ int
+ |
+
+
+
+ Maximum depth to print. + |
+
+ 0
+ |
+
style |
+
+ Literal['ansi', 'ascii', 'const', 'const_bold', 'rounded', 'double']
+ |
+
+
+
+ The style of the tree + |
+
+ 'const'
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+
+ |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.tar") as archive:
+ archive.tree()
+ # hello-world
+ # ├── .github
+ # │ └── workflows
+ # │ ├── docs.yml
+ # │ ├── release.yml
+ # │ └── test.yml
+ # ├── .gitignore
+ # ├── docs
+ # │ └── index.md
+ # ├── pyproject.toml
+ # ├── README.md
+ # ├── src
+ # │ └── hello-world
+ # │ └── __init__.py
+ # ├── tests
+ # │ ├── test_hello_world.py
+ # │ └── __init__.py
+ # └── LICENSE
+
src/archivefile/_core.py
write
+
+
+write(file: StrPath, arcname: StrPath | None = None, compression_type: ZipCompression | None = None, compression_level: int | None = None) -> None
+
Write a single file to the archive.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
file |
+
+ StrPath
+ |
+
+
+
+ The path of the file to be added to the archive. + |
+ + required + | +
arcname |
+
+ StrPath
+ |
+
+
+
+ The name which the file will have in the archive. +Default is the basename of the file. + |
+
+ None
+ |
+
compression_type |
+
+ ZipCompression
+ |
+
+
+
+ The compression method to be used. If None, the default compression +method of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
compression_level |
+
+ int
+ |
+
+
+
+ The compression level to be used. If None, the default compression +level of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+
+ |
+
Examples:
+from pathlib import Path
+
+from archivefile import ArchiveFile
+
+file = Path("hello.txt")
+file.write_text("world")
+
+with ArchiveFile("newarchive.zip", "w") as archive:
+ archive.write(file)
+ archive.get_names()
+ # ('hello.txt',)
+
src/archivefile/_core.py
582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 |
|
write_bytes
+
+
+write_bytes(data: bytes, arcname: StrPath, compression_type: ZipCompression | None = None, compression_level: int | None = None) -> None
+
Write the bytes data
to a file within the archive named arcname
.
Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
data |
+
+ bytes
+ |
+
+
+
+ The bytes data to write to the archive. + |
+ + required + | +
arcname |
+
+ StrPath
+ |
+
+
+
+ The name which the file will have in the archive. + |
+ + required + | +
compression_type |
+
+ ZipCompression
+ |
+
+
+
+ The compression method to be used. If None, the default compression +method of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
compression_level |
+
+ int
+ |
+
+
+
+ The compression level to be used. If None, the default compression +level of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+
+ |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("newarchive.zip", "w") as archive:
+ archive.write_bytes(b"hello world", arcname="bytesworld.txt")
+ archive.get_names()
+ # ('bytesworld.txt',)
+ archive.read_bytes("bytesworld.txt")
+ # b'hello world'
+
src/archivefile/_core.py
write_text
+
+
+write_text(data: str, arcname: StrPath, encoding: str | None = 'utf-8', errors: Literal['strict', 'ignore', 'replace', 'backslashreplace', 'surrogateescape', 'xmlcharrefreplace', 'namereplace'] | None = None, newline: Literal['', '\n', '\r', '\r\n'] | None = None, compression_type: ZipCompression | None = None, compression_level: int | None = None) -> None
+
Write the string data
to a file within the archive named arcname
.
Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
data |
+
+ str
+ |
+
+
+
+ The text data to write to the archive. + |
+ + required + | +
arcname |
+
+ StrPath
+ |
+
+
+
+ The name which the file will have in the archive. + |
+ + required + | +
encoding |
+
+ str | None
+ |
+
+
+
+ Encoding of the given data. Default is |
+
+ 'utf-8'
+ |
+
errors |
+
+ Literal['strict', 'ignore', 'replace', 'backslashreplace', 'surrogateescape', 'xmlcharrefreplace', 'namereplace'] | None
+ |
+
+
+
+ String that specifies how encoding and decoding errors are to be handled. + |
+
+ None
+ |
+
newline |
+
+ Literal['', '\n', '\r', '\r\n'] | None
+ |
+
+
+
+ If newline is None, any '\n' characters written are translated to the system default line separator, |
+
+ None
+ |
+
compression_type |
+
+ ZipCompression
+ |
+
+
+
+ The compression method to be used. If None, the default compression +method of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
compression_level |
+
+ int
+ |
+
+
+
+ The compression level to be used. If None, the default compression +level of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+
+ |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("newarchive.zip", "w") as archive:
+ archive.write_text("hello world", arcname="textworld.txt")
+ archive.get_names()
+ # ('textworld.txt',)
+ archive.read_text("textworld.txt")
+ # 'hello world'
+
src/archivefile/_core.py
654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 |
|
writeall
+
+
+writeall(dir: StrPath, root: StrPath | None = None, glob: str = '*', recursive: bool = True, compression_type: ZipCompression | None = None, compression_level: int | None = None) -> None
+
Write a directory to the archive.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
dir |
+
+ StrPath
+ |
+
+
+
+ The path of the directory to be added to the archive. + |
+ + required + | +
root |
+
+ StrPath
+ |
+
+
+
+ Directory that will be the root directory of the archive, all paths in the archive will be relative to it. +This MUST be a component of given directory path. Default is the parent of the given directory. + |
+
+ None
+ |
+
glob |
+
+ str
+ |
+
+
+
+ Only write files that match this glob pattern to the archive. + |
+
+ '*'
+ |
+
recursive |
+
+ bool
+ |
+
+
+
+ Recursively write all the files in the given directory. Default is True. + |
+
+ True
+ |
+
compression_type |
+
+ ZipCompression
+ |
+
+
+
+ The compression method to be used. If None, the default compression +method of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
compression_level |
+
+ int
+ |
+
+
+
+ The compression level to be used. If None, the default compression +level of the archive will be used. +This ONLY applies to zip files and has no effect on other archives. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+
+ |
+
Examples:
+from archivefile import ArchiveFile
+
+with ArchiveFile("source.tar.gz", "w:gz") as archive:
+ archive.writeall(dir="hello-world/", glob="*.py")
+ archive.tree()
+ # hello-world
+ # ├── src
+ # │ └── hello_world
+ # │ └── __init__.py
+ # └── tests
+ # └── __init__.py
+
src/archivefile/_core.py
793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 |
|
ZipCompression
+
+
+
+ Bases: IntEnum
Compression algorithms for ZipFile
+ + + + +
ZIP_BZIP2
+
+
+
+ class-attribute
+ instance-attribute
+
+
+The numeric constant for the BZIP2 compression method. This requires the bz2 module.
+
ZIP_DEFLATED
+
+
+
+ class-attribute
+ instance-attribute
+
+
+The numeric constant for the usual ZIP compression method. This requires the zlib module.
+
ZIP_LZMA
+
+
+
+ class-attribute
+ instance-attribute
+
+
+The numeric constant for the LZMA compression method. This requires the lzma module.
+
OpenArchiveMode
+
+
+
+ module-attribute
+
+
+OpenArchiveMode: TypeAlias = Literal['r', 'r:*', 'r:', 'r:gz', 'r:bz2', 'r:xz', 'w', 'w:', 'w:gz', 'w:bz2', 'w:xz', 'x', 'x:', 'x:', 'x:gz', 'x:bz2', 'x:xz', 'a', 'a:']
+
ArchiveMember
+
+
+
+ Bases: BaseModel
checksum
+
+
+
+ class-attribute
+ instance-attribute
+
+
+checksum: int = 0
+
compressed_size
+
+
+
+ class-attribute
+ instance-attribute
+
+
+
datetime
+
+
+
+ class-attribute
+ instance-attribute
+
+
+
is_dir
+
+
+
+ class-attribute
+ instance-attribute
+
+
+is_dir: bool = False
+
is_file
+
+
+
+ class-attribute
+ instance-attribute
+
+
+is_file: bool = False
+
is_archive
+
+
+Check whether the given archive file is a supported archive or not.
+ + + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
file |
+
+ StrPath
+ |
+
+
+
+ Path to the archive file. + |
+ + required + | +
Returns:
+Type | +Description | +
---|---|
+ bool
+ |
+
+
+
+ True if the archive is supported, False otherwise. + |
+
src/archivefile/_utils.py