Easy Archive

`py_simple.easy_archive`

easy_archive is meant to simplify zipping and unzipping files and folders.

`EasyArchiveError`

Bases: Exception

Raised when an archive operation cannot be completed.

Parameters:

Name	Type	Description	Default
`message`	`str`	Description of what went wrong.	required

`add_to_zip(zip_path, file_to_add)`

Adds a single file to an existing .zip archive.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the existing .zip file.	required
`file_to_add`	`str`	Path of the file to add to the archive.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the file was added.

Example

The Py_simple WayThe Traditional Way

from py_simple import add_to_zip

add_to_zip("backup.zip", "extra_notes.txt")

import zipfile

with zipfile.ZipFile("backup.zip", "a", zipfile.ZIP_DEFLATED) as zf:
    zf.write("extra_notes.txt")

`extract_file_from_zip(zip_path, filename, destination='.')`

Extracts a single file from a zip archive.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the zip file.	required
`filename`	`str`	Name of the file inside the archive.	required
`destination`	`str`	Folder to extract the file into.	`'.'`

Returns:

Name	Type	Description
`str`	`str`	Path to the extracted file.

Raises:

Type	Description
`EasyArchiveError`	If the zip file is missing or invalid, the destination is an existing file, or the requested file is not present in the archive.

Example

The Py_simple WayThe Traditional Way

from py_simple import extract_file_from_zip

extract_file_from_zip("backup.zip", "notes.txt", "restored")

import zipfile

with zipfile.ZipFile("backup.zip") as zf:
    zf.extract("notes.txt", "restored")

`get_zip_file_count(zip_path)`

Returns the total number of files and directories stored in a .zip archive.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the .zip archive to inspect.	required

Returns:

Name	Type	Description
`int`	`int`	Number of items contained in the archive.

Raises:

Type	Description
`EasyArchiveError`	If the file does not exist or is not a valid zip file.

Example

The Py_simple WayThe Traditional Way

from py_simple import get_zip_file_count

count = get_zip_file_count("backup.zip")  # -> 5

import zipfile

with zipfile.ZipFile("backup.zip", "r") as zf:
    count = len(zf.namelist())

`is_zip_file(path)`

Checks whether a given path is a valid zip archive.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to check.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if path exists and is a valid zip file, False otherwise (including when the path doesn't exist).

Example

The Py_simple WayThe Traditional Way

from py_simple import is_zip_file

is_zip_file("backup.zip")  # -> True

import zipfile

zipfile.is_zipfile("backup.zip")

`list_zip_contents(zip_path)`

Lists the files inside a .zip archive without extracting them.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the .zip file to inspect.	required

Returns:

Name	Type	Description
`list`	`list`	Filenames stored in the archive.

Example

The Py_simple WayThe Traditional Way

from py_simple import list_zip_contents

contents = list_zip_contents("backup.zip")

import zipfile

with zipfile.ZipFile("backup.zip", "r") as zf:
    contents = zf.namelist()

`unzip_file(zip_path, destination='.')`

Extracts every file in a .zip archive into a destination folder. The destination folder is created automatically if it doesn't exist.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the .zip file to extract.	required
`destination`	`str`	Folder to extract into. Defaults to the current working directory.	`'.'`

Returns:

Name	Type	Description
`str`	`str`	The destination folder path.

Example

The Py_simple WayThe Traditional Way

from py_simple import unzip_file

unzip_file("backup.zip", "restored")

import os
import zipfile

zip_path, destination = "backup.zip", "restored"
os.makedirs(destination, exist_ok=True)
with zipfile.ZipFile(zip_path, "r") as zf:
    zf.extractall(destination)

`zip_contains_file(zip_path, filename)`

Checks whether a zip archive contains a specific file.

Parameters:

Name	Type	Description	Default
`zip_path`	`str`	Path to the .zip file to inspect.	required
`filename`	`str`	Name of the file to look for inside the archive.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the file is present, False otherwise.

Raises:

Type	Description
`EasyArchiveError`	If the zip file is missing or invalid.

Example

The Py_simple WayThe Traditional Way

from py_simple import zip_contains_file

has_notes = zip_contains_file("backup.zip", "notes.txt")

import zipfile

with zipfile.ZipFile("backup.zip", "r") as zf:
    has_notes = "notes.txt" in zf.namelist()

`zip_files(file_paths, zip_name)`

Zips a list of individual files into a single .zip archive. If two files share the same filename (e.g. from different folders), the later one is automatically renamed inside the archive instead of silently overwriting the first.

Parameters:

Name	Type	Description	Default
`file_paths`	`list`	Paths of the files to include.	required
`zip_name`	`str`	Name/path for the resulting zip file. Must end in '.zip'.	required

Returns:

Name	Type	Description
`str`	`str`	Path to the created zip file.

Example

The Py_simple WayThe Traditional Way

from py_simple import zip_files

zip_files(["notes.txt", "todo.md"], "backup.zip")

import os
import zipfile

file_paths = ["notes.txt", "todo.md"]
with zipfile.ZipFile("backup.zip", "w", zipfile.ZIP_DEFLATED) as zf:
    for path in file_paths:
        if os.path.isfile(path):
            zf.write(path, os.path.basename(path))

`zip_folder(folder_path, zip_name=None)`

Zips an entire folder (including subfolders) into a single .zip file.

Parameters:

Name	Type	Description	Default
`folder_path`	`str`	Path to the folder to zip.	required
`zip_name`	`str`	Name/path for the resulting zip file. Defaults to the folder's own name with '.zip' appended.	`None`

Returns:

Name	Type	Description
`str`	`str`	Path to the created zip file.

Example

The Py_simple WayThe Traditional Way

from py_simple import zip_folder

zip_folder("my_project")  # -> 'my_project.zip'

import os
import zipfile

folder_path = "my_project"
zip_name = "my_project.zip"
with zipfile.ZipFile(zip_name, "w", zipfile.ZIP_DEFLATED) as zf:
    for root, _, files in os.walk(folder_path):
        for file in files:
            full_path = os.path.join(root, file)
            arcname = os.path.relpath(full_path, folder_path)
            zf.write(full_path, arcname)