unishell 2.3.3

Core cross-platform Python library for filesystem operations

Unishell is a powerful, cross-platform, and intuitive Python library for working with files, directories, and text data. It provides two API styles: the shell-style unishell.sh_space and the Python-style unishell.

Two API styles

1. UniShell - Shell style

A high-level interface inspired by the Unix command line/Cmd. It automatically expands paths with environment variables (%VAR%), special notations (~, .., .), and supports some method chaining. To avoid polluting the global environment, it is recommended to import functions in separate files, create them in them, and then import them in separate modules.

#shell_module.py
from unishell.sh_space import *
def shell_function():
    cd("~")
    mkfile("1.txt")
    file("1.txt") < "data"

2. Python-style ORM

Classes for working with the file system in an object-oriented style.

#python_module.py
from unishell import File,Unishell
def shell_function():
    sh = UniShell()
    sh.cd("~")
    file = File("1.txt")
    file.create()
    file.content = "data"

Installation

pip install unishell

Main modules

1. Working with files and folders
   Create, edit, delete, move, copy files and folders with automatic path expansion.

   from unishell import shell
   

2. Working with encodings
   Allows recognition and recoding into minimal encoding. Functions:

   from unishell import detect_encoding,determine_minimal_encoding
   

   Dependencies: chardet (LGPL) - for automatic encoding detection.

3. Working with archives
   Editing archives with passwords and extracting individual files. Multiple formats are supported. Requires appropriate libraries.

   from unishell import Archive
   

   Dependencies: py7zr (LGPL-2.1), pyzipper (MIT), rarfile (ISC)

4. Working with the Windows registry. Create and delete users by SID, change passwords. Edit PATH, AutoRun, and AutoRunOnce. CurrentUser, User, Users

   from unishell.regedit import CurUser, User, Users,PATH, AutoRun, AutoRunOnce
   

   Dependencies: pywin32(PSF)

Implementation Features

1. Cross-platform - a single API for Windows, Linux, and macOS
2. Two API levels - shell-style (UniShell) and Python-style (ORM)
3. PropCase(PropertyCase) - many attributes are changed through properties.
4. Avoiding exceptions - Most commands avoid exceptions, returning None when necessary.
5. Lazy operations - files are read and created only when necessary
6. Stream operations - support for operators >>, >, <<, < for working with content

License

UniShell is distributed under the MIT License. See the LICENSE file for details.

Dependency Licenses

The project uses the following dependencies and their licenses:

• chardet — LGPL
• py7zr — LGPL-2.1-or-later
• pyzipper — MIT
• rarfile — ISC
• pywin32 - PSF (Python Software Foundation License)

All dependencies are compatible with the MIT License.
Requirements:

• Python 3.10+

Documentation

UniShell API: Complete list of signatures with examples (AI-generated)

Constructor

shell = UniShell(
    sep: str = "\n",
    current_dir = os.getcwd(),
    default_encoding: str = 'utf-8',
    autodetect_encoding: bool = False,
    parms : ViewPort = ViewPort()
)

Methods

file

def file(self, path: str | Path, encoding: str|None = None) -> File
sh.file("demo.txt")

files

def files(self, *files: str|Path|File, encoding: str|None = None, sep="\n") -> Files
sh.files("1.txt","2.txt")

cd

def cd(self, path: str|Path) -> UniShell
sh.cd("..")

copy

def copy(self, from_path: str|Path, to_path: str|Path, *, follow_symlinks=True, ignore_errors=False) -> UniShell
sh.copy("a.txt", "b.txt")

mkdir

def mkdir(self, path: str|Path, mode=0o777, parents=False, exist_ok=False, ignore_errors=False) -> UniShell
sh.mkdir("d")

mkfile

def mkfile(self, path: str|Path, ignore_errors=False) -> UniShell
sh.mkfile("new.txt")

rmfile

def rmfile(self, path: str|Path, ignore_errors=False) -> UniShell
sh.rmfile("f.txt")

rmdir

def rmdir(self, path: str|Path, ignore_errors=False, onexc=None) -> UniShell
sh.rmdir("folder")

make_archive

def make_archive(self, from_path: str|Path, to_path: str|Path|None = None, format: str = "zip", owner: Optional[str] = None, group: Optional[str] = None, ignore_errors: bool = False) -> UniShell
sh.make_archive("f", "f.zip")

extract_archive

def extract_archive(self, archive_path: str|Path, extract_dir: Optional[str|Path]=None, format=None, ignore_errors=False) -> UniShell
sh.extract_archive("f.zip", "outdir")

chmod

def chmod(self, path: str|Path, mode: int, ignore_errors=False) -> UniShell
sh.chmod("file.txt", 0o400)

nano

def nano(self, path: str|Path, edit_txt="notepad", ignore_errors=False) -> UniShell
sh.nano("t.txt")

remove

def remove(self, path: str|Path, ignore_errors=False) -> UniShell
sh.remove("obj.txt")

make

def make(self, path: str|Path, is_file: bool|None = None, ignore_errors: bool = False) -> UniShell
sh.make("demo.dir", is_file=False)

ls

def ls(self, path: str|Path = ".", details: bool = False, ignore_errors: bool = False) -> Union[list[str], dict[str,Any]]
sh.ls("some_dir", details=True)

to_abspath

def to_abspath(self, path:str|Path|File|Dir) -> Path
sh.to_abspath("~/%USER%/1.txt")

recode

def recode(self, file_path: str|Path, to_encoding: str, from_encoding: Optional[str]=None, ignore_errors: bool = False) -> UniShell
sh.recode("ru.txt", to_encoding="cp1251")

parms

sh.parms["TEST"] = "value"
print(sh.parms.all())

---

File

f = File("test.txt", encoding="utf-8")

• content: str (property)
• @content.setter (content: str)
• @contentdeleter
• create(mode=438, ignore_errors=True) -> File
• remove() -> None
• nano(edit_txt="notepad") -> None
• chmod(mode: int) -> None
• recode(to_encoding=None, from_encoding=None) -> None
• name: str
• parent: Dir
• extension: str
• on_disk() -> bool
• sizeof() -> int
• created_utc(), modified_utc(), accessed_utc() -> datetime
• created_lcl(), modified_lcl(), accessed_lcl() -> datetime
• is_symlink() -> bool
• hidden (property)
• metadata() -> dict

Examples:

f = File("tt.txt")
f.content = "123"
f.create()
f.metadata()
f.chmod(0o777)
f.remove()

---

Dir

d = Dir("data/")

• create(mode=0o777, parents=False, ignore_errors=False) -> None
• add(path) -> Dir
• move_to(dir) -> Dir
• rename(new_name) -> None
• on_disk() -> bool
• chmod(mode) -> None
• name (property): str
• parent (property): Dir
• hidden (property): bool
• hidden.setter: bool
• len_files_and_dirs(recursive=True, symlinks=False) -> dict
• sizeof(recursive=True, symlink=False) -> int
• created_utc, modified_utc, accessed_utc() -> datetime
• created_lcl, modified_lcl, accessed_lcl() -> datetime
• is_symlink() -> bool
• metadata() -> dict
• truediv(name)
• iter()
• str()
• repr()

Example:

dir = Dir("a") dir.create() for entry in dir: print(entry) dir.hidden = True

---

Files

f = Files("a.txt", "b.txt")
f.files # list[File]

• stream_getData() -> str

---

Archive

arc = Archive("z.zip")

• init(path: Path|str, format: str|None=None, password: str|None=None)
• iter() -> Iterator[str]
• add(path, arcname=None) -> None
• extract(member=None, path=".") -> None
• list_files() -> list[str]
• create() -> Archive
• create_from(path, format, files: list, password=None) -> Archive [classmethod]

Example:

arc.add("1.txt") print(list(arc)) arc.extract(path="out")

---

ViewPort

v = ViewPort()
v["A"] = 12
print("A" in v)

• set_gl(name: str, value: str)
• del_gl(name: str)
• all() -> dict
• set_(name: str, value:Any, link=False)
• sets(parms: dict, link=False)
• del_(name: str)
• dels(parms: list)
• getitem, setitem, delitem, contains

---

encoding_utils

detect_encoding(path, sample_size=65536, ignore_errors=False) -> Optional[str]
determine_minimal_encoding(content: str) -> str
check_bom(data: bytes) -> Optional[str]

Example:

determine_minimal_encoding("text")

---

unishell_win.regedit

User/CurrentUser/Users

• User(id=None, name=None, domain="")
  • .create(name, password, ...)
  • .delete()
  • .password_chg(old,new)
  • .exists(id=None, name=None, domain="") [staticmethod]
  • .getCurUserSid() [staticmethod]
  • id, name, domain, type (property)
  • PATH, AutoRun, AutoRunOnce (property)
  • repr
• Users.local() -> list[User]
• Users.all(name=None, domain=None) -> list[User]
• iter
• repr

Examples:

u = User.create("u1","1234") Users.all() print(u.id, u.name)

PATH

PATH(user: User|CurrentUser|Users|str|None = None)

• add(path)
• pop(path)
• all() -> list[str]
• get()
• contains, iter, getitem, setitem, delitem, len, repr, str

Example:

PATH.add(r"C:\bin") PATH[0]

AutoRun, AutoRunOnce

AutoRun(user: ... = None)

• add(name, path)
• set(name, path)
• pop(name)
• get(name)
• all() -> dict[str, str]
• keys() -> list[str]
• values() -> list[str]
• items() -> list[tuple[str,str]]
• contains, iter, getitem, setitem, delitem, len, repr

Example:

AutoRun.add("App", r"C:\path\app.exe") print(AutoRun[0], AutoRun["App"])

---