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 path does not end in '.zip'.

This only covers the extension check — a path that ends in '.zip' but is not a valid archive is not raised on; those functions return None, [], or False instead.

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, False if zip_path does not exist or is not a valid zip file, or file_to_add does not exist.

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")

`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, or an empty list if zip_path does not exist or is not a valid zip file.

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, or None if zip_path does not exist, is not a valid zip file, or destination already exists as a regular file.

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_files(file_paths, zip_name)`

Zips a list of individual files into a single .zip archive. Files that don't exist are skipped with a warning instead of failing the whole operation. 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, or None if none of the given files exist.

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, or None if folder_path does not exist.

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)