windowsctxmenu 1.0.0__py3-none-any.whl

windowsctxmenu/__init__.py

@@ -0,0 +1,14 @@
+__version__ = "1.0.0"
+
+from .addmenu import add_handler, add_shell, unblock
+from .contextmenu import block, remove_handler, remove_shell, remove_shellnew
+
+__all__ = [
+    "remove_shell",
+    "remove_handler",
+    "remove_shellnew",
+    "block",
+    "add_shell",
+    "add_handler",
+    "unblock",
+]

windowsctxmenu/addmenu.py

@@ -0,0 +1,79 @@
+import winreg
+
+from .utils import (
+    ACCESS,
+    BLOCKED_PATH,
+    CLASSES,
+    HIVES,
+    read_value,
+    resolve_clsid,
+    scope_bases,
+    set_value,
+)
+
+
+def add_shell(
+    name,
+    command,
+    scope="file",
+    label=None,
+    icon=None,
+    hive="HKCU",
+    extended=False,
+):
+    root = HIVES[hive]
+    results = []
+    for base in scope_bases(root, scope):
+        rel = base + "\\shell\\" + name
+        path = CLASSES + rel
+        try:
+            set_value(root, path, "", label or name)
+            if icon:
+                set_value(root, path, "Icon", icon)
+            if extended:
+                set_value(root, path, "Extended", "")
+            set_value(root, path + "\\command", "", command)
+            results.append(f"added: [{hive}] {rel}")
+        except PermissionError:
+            results.append(f"no permission (run as admin): [{hive}] {rel}")
+    if not results:
+        results.append(f"no targets: {name}  (scope={scope})")
+    return results
+
+
+def add_handler(name, clsid, scope="file", hive="HKCU"):
+    root = HIVES[hive]
+    results = []
+    for base in scope_bases(root, scope):
+        rel = base + "\\shellex\\ContextMenuHandlers\\" + name
+        path = CLASSES + rel
+        try:
+            set_value(root, path, "", clsid)
+            results.append(f"added: [{hive}] {rel}")
+        except PermissionError:
+            results.append(f"no permission (run as admin): [{hive}] {rel}")
+    if not results:
+        results.append(f"no targets: {name}  (scope={scope})")
+    return results
+
+
+def unblock(name_or_clsid):
+    clsid = resolve_clsid(name_or_clsid)
+    if clsid is None:
+        return [f"unknown CLSID: {name_or_clsid!r}"]
+    results = []
+    for hive, root in HIVES.items():
+        try:
+            with winreg.OpenKey(
+                root, BLOCKED_PATH, 0, winreg.KEY_READ | winreg.KEY_WRITE | ACCESS
+            ) as handle:
+                if read_value(handle, clsid) is None:
+                    results.append(f"not blocked: [{hive}] {clsid}  ({name_or_clsid})")
+                else:
+                    winreg.DeleteValue(handle, clsid)
+                    results.append(f"unblocked: [{hive}] {clsid}  ({name_or_clsid})")
+        except FileNotFoundError:
+            results.append(f"not blocked: [{hive}] {clsid}  ({name_or_clsid})")
+        except PermissionError:
+            results.append(f"no permission (run as admin): [{hive}] {clsid}")
+    return results

windowsctxmenu/cli.py

@@ -0,0 +1,49 @@
+"""The ``switchmenu`` command: toggle the Windows 11 classic context menu."""
+
+import subprocess
+import time
+import winreg
+
+_KEY = r"Software\Classes\CLSID\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}\InprocServer32"
+_PARENT = _KEY.rsplit("\\", 1)[0]
+
+_ACCESS = winreg.KEY_WOW64_64KEY
+
+
+def _is_classic_active() -> bool:
+    try:
+        with winreg.OpenKeyEx(winreg.HKEY_CURRENT_USER, _KEY, 0,
+                              winreg.KEY_READ | _ACCESS) as k:
+            value, kind = winreg.QueryValueEx(k, "")  # "" == the (Default) value
+            return kind == winreg.REG_SZ and value == ""
+    except FileNotFoundError:
+        return False
+
+
+def _restart_explorer() -> None:
+    subprocess.run(["taskkill", "/f", "/im", "explorer.exe"],
+                   check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    time.sleep(1)
+    subprocess.Popen(["explorer.exe"])
+
+
+def main() -> None:
+    if _is_classic_active():
+        winreg.DeleteKeyEx(winreg.HKEY_CURRENT_USER, _KEY, _ACCESS, 0)
+        try:
+            winreg.DeleteKeyEx(winreg.HKEY_CURRENT_USER, _PARENT, _ACCESS, 0)
+        except OSError:
+            # Parent has other subkeys or is already gone; that's fine.
+            pass
+        print("Switched to: new menu")
+    else:
+        with winreg.CreateKeyEx(winreg.HKEY_CURRENT_USER, _KEY, 0,
+                                winreg.KEY_WRITE | _ACCESS) as k:
+            winreg.SetValueEx(k, "", 0, winreg.REG_SZ, "")
+        print("Switched to: classic menu")
+
+    _restart_explorer()
+
+
+if __name__ == "__main__":
+    main()

windowsctxmenu/contextmenu.py

@@ -0,0 +1,147 @@
+import winreg
+
+from .utils import (
+    ACCESS,
+    BLOCKED_PATH,
+    CLASSES,
+    HIVES,
+    SPECIAL_CLSIDS,
+    TYPE_SUFFIX,
+    delete_key_recursive,
+    read_value,
+    resolve_clsid,
+    scope_bases,
+)
+
+
+def _find_child_name(root, shell_path, name):
+    try:
+        handle = winreg.OpenKey(root, shell_path, 0, winreg.KEY_READ | ACCESS)
+    except FileNotFoundError:
+        return None
+    target = name.lower()
+    try:
+        i = 0
+        while True:
+            try:
+                child = winreg.EnumKey(handle, i)
+            except OSError:
+                break
+            i += 1
+            if child.lower() == target:
+                return child
+            try:
+                sub = winreg.OpenKey(handle, child, 0, winreg.KEY_READ | ACCESS)
+            except OSError:
+                continue
+            try:
+                for vname in ("", "MUIVerb"):
+                    label = read_value(sub, vname)
+                    if label and label.lower() == target:
+                        return child
+            finally:
+                winreg.CloseKey(sub)
+    finally:
+        winreg.CloseKey(handle)
+    return None
+
+
+def _find_handler_name(root, base_path, name):
+    try:
+        handle = winreg.OpenKey(root, base_path, 0, winreg.KEY_READ | ACCESS)
+    except FileNotFoundError:
+        return None
+    target = name.lower()
+    try:
+        i = 0
+        while True:
+            try:
+                child = winreg.EnumKey(handle, i)
+            except OSError:
+                break
+            i += 1
+            if child.lower() == target:
+                return child
+    finally:
+        winreg.CloseKey(handle)
+    return None
+
+
+def _remove(name, scope, kind):
+    suffix = TYPE_SUFFIX[kind]
+    results = []
+    found_any = False
+    for hive_name, root in HIVES.items():
+        for base in scope_bases(root, scope):
+            rel = base + "\\" + suffix
+            reg_path = CLASSES + rel
+            if kind == "handler":
+                real = _find_handler_name(root, reg_path, name)
+            else:
+                real = _find_child_name(root, reg_path, name)
+            if real is None:
+                continue
+            found_any = True
+            full = reg_path + "\\" + real
+            try:
+                if delete_key_recursive(root, full):
+                    results.append(f"deleted: [{hive_name}] {rel}\\{real}  ({name})")
+            except PermissionError:
+                results.append(
+                    f"no permission (run as admin): [{hive_name}] {rel}\\{real}  ({name})"
+                )
+    if not found_any:
+        results.append(f"not found: {name}  (scope={scope}, type={kind})")
+    return results
+
+
+def remove_shell(name, scope="all"):
+    return _remove(name, scope, "shell")
+
+
+def remove_handler(name, scope="all"):
+    target = SPECIAL_CLSIDS.get(name.strip().lower(), name)
+    return _remove(target, scope, "handler")
+
+
+def remove_shellnew(key_path):
+    results = []
+    found_any = False
+    for hive_name, root in HIVES.items():
+        full = CLASSES + key_path + "\\ShellNew"
+        try:
+            winreg.CloseKey(winreg.OpenKey(root, full, 0, winreg.KEY_READ | ACCESS))
+        except FileNotFoundError:
+            continue
+        found_any = True
+        try:
+            if delete_key_recursive(root, full):
+                results.append(f"deleted ShellNew: [{hive_name}] {key_path}")
+        except PermissionError:
+            results.append(
+                f"no permission (run as admin): [{hive_name}] {key_path}\\ShellNew"
+            )
+    if not found_any:
+        results.append(f"not found: {key_path}\\ShellNew")
+    return results
+
+
+def block(name_or_clsid):
+    clsid = resolve_clsid(name_or_clsid)
+    if clsid is None:
+        catalog = ", ".join(sorted(SPECIAL_CLSIDS))
+        return [f"unknown CLSID: {name_or_clsid!r}. Pass a {{CLSID}} or: {catalog}."]
+    results = []
+    for hive_name, root in HIVES.items():
+        try:
+            with winreg.CreateKeyEx(
+                root, BLOCKED_PATH, 0, winreg.KEY_READ | winreg.KEY_WRITE | ACCESS
+            ) as handle:
+                if read_value(handle, clsid) is not None:
+                    results.append(f"already blocked: [{hive_name}] {clsid}  ({name_or_clsid})")
+                else:
+                    winreg.SetValueEx(handle, clsid, 0, winreg.REG_SZ, name_or_clsid)
+                    results.append(f"blocked: [{hive_name}] {clsid}  ({name_or_clsid})")
+        except PermissionError:
+            results.append(f"no permission (run as admin): [{hive_name}] {clsid}  ({name_or_clsid})")
+    return results

windowsctxmenu/utils.py

@@ -0,0 +1,132 @@
+import fnmatch
+import winreg
+
+ACCESS = winreg.KEY_WOW64_64KEY
+
+HIVES = {
+    "HKCU": winreg.HKEY_CURRENT_USER,
+    "HKLM": winreg.HKEY_LOCAL_MACHINE,
+}
+
+CLASSES = "Software\\Classes\\"
+
+TYPE_SUFFIX = {
+    "shell": "shell",
+    "handler": r"shellex\ContextMenuHandlers",
+}
+
+BLOCKED_PATH = r"Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked"
+
+SCOPE_BASES = {
+    "file": ["*"],
+    "directory": ["Directory"],
+    "background": [r"Directory\Background"],
+    "folder": ["Folder"],
+    "drive": ["Drive"],
+    "allfiles": ["AllFilesystemObjects"],
+    "image": [r"SystemFileAssociations\image"],
+    "video": [r"SystemFileAssociations\video"],
+    "audio": [r"SystemFileAssociations\audio"],
+}
+SCOPE_BASES["all"] = [
+    b
+    for k in ("file", "directory", "background", "folder", "drive", "allfiles")
+    for b in SCOPE_BASES[k]
+]
+
+SPECIAL_CLSIDS = {
+    "photos": "{BFE0E2A4-C70C-4AD7-AC3D-10D1ECEBB5B4}",
+    "edit with photos": "{BFE0E2A4-C70C-4AD7-AC3D-10D1ECEBB5B4}",
+    "share": "{E2BF9676-5F8F-435C-97EB-11607A5BEDF7}",
+    "give access to": "{f81e9010-6ea4-11ce-a7ff-00aa003ca9f6}",
+    "cast to device": "{7AD84985-87B4-4a16-BE58-8B72A5B390F7}",
+    "include in library": "{3dad6c5d-2167-4cae-9914-f99e41c12cfa}",
+    "restore previous versions": "{596AB062-B4D2-4215-9F74-E9109B0A8153}",
+    "scan with microsoft defender": "{09A47860-11B0-4DA5-AFA5-26D86198A780}",
+    "edit in notepad": "{CA6CC9F1-867A-481E-951E-A28C5E4F01EA}",
+}
+
+
+def is_guid(text):
+    text = text.strip()
+    return text.startswith("{") and text.endswith("}") and len(text) == 38
+
+
+def resolve_clsid(name_or_clsid):
+    if is_guid(name_or_clsid):
+        return name_or_clsid
+    return SPECIAL_CLSIDS.get(name_or_clsid.strip().lower())
+
+
+def read_value(handle, value_name):
+    try:
+        value, _ = winreg.QueryValueEx(handle, value_name)
+    except OSError:
+        return None
+    return value if isinstance(value, str) else None
+
+
+def set_value(root, path, value_name, value):
+    with winreg.CreateKeyEx(root, path, 0, winreg.KEY_WRITE | ACCESS) as handle:
+        winreg.SetValueEx(handle, value_name, 0, winreg.REG_SZ, value)
+
+
+def match_subkeys(root, base_path, pattern):
+    try:
+        handle = winreg.OpenKey(root, base_path, 0, winreg.KEY_READ | ACCESS)
+    except FileNotFoundError:
+        return []
+    pat = pattern.lower()
+    names = []
+    try:
+        i = 0
+        while True:
+            try:
+                child = winreg.EnumKey(handle, i)
+            except OSError:
+                break
+            i += 1
+            if fnmatch.fnmatch(child.lower(), pat):
+                names.append(child)
+    finally:
+        winreg.CloseKey(handle)
+    return names
+
+
+def scope_bases(root, scope):
+    if scope.startswith("sfa:"):
+        return [
+            "SystemFileAssociations\\" + n
+            for n in match_subkeys(root, CLASSES + "SystemFileAssociations", scope[4:])
+        ]
+    if scope.startswith("."):
+        return ["SystemFileAssociations\\" + scope]
+    if "*" in scope or "?" in scope:
+        return match_subkeys(root, CLASSES.rstrip("\\"), scope)
+    try:
+        return SCOPE_BASES[scope]
+    except KeyError:
+        valid = ", ".join(sorted(SCOPE_BASES))
+        raise ValueError(
+            f"Invalid scope: {scope!r}. Valid: {valid}, '.ext', 'VLC.*', 'sfa:<glob>'."
+        )
+
+
+def delete_key_recursive(root, subkey):
+    try:
+        handle = winreg.OpenKey(
+            root, subkey, 0, winreg.KEY_READ | winreg.KEY_WRITE | ACCESS
+        )
+    except FileNotFoundError:
+        return False
+    try:
+        while True:
+            try:
+                child = winreg.EnumKey(handle, 0)
+            except OSError:
+                break
+            delete_key_recursive(handle, child)
+    finally:
+        winreg.CloseKey(handle)
+    winreg.DeleteKeyEx(root, subkey, ACCESS, 0)
+    return True

windowsctxmenu-1.0.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: windowsctxmenu
+Version: 1.0.0
+Summary: Add, remove and block Windows right-click context menu entries from Python.
+Project-URL: Homepage, https://github.com/offerrall/windowsctxmenu
+Project-URL: Repository, https://github.com/offerrall/windowsctxmenu
+Author: windowsctxmenu authors
+License: MIT License
+        
+        Copyright (c) 2026 Beltrán Offerrall
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: context-menu,registry,shell,windows,winreg
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# windowsctxmenu
+
+Get your Windows right-click menu exactly the way you want it, from Python.
+
+The idea: you write **one script** with your setup (what to remove, what to add,
+what to block) and carry it to every new PC or every reinstall. Run it and your
+context menu is identical everywhere — no manual registry editing.
+
+## Requirements
+
+- Windows 11
+- Python >= 3.10
+
+## Installation
+
+```bash
+pip install windowsctxmenu
+```
+
+## API
+
+```python
+from windowsctxmenu import (
+    add_shell, add_handler, unblock,
+    remove_shell, remove_handler, remove_shellnew, block,
+)
+```
+
+| Function | What it does |
+| --- | --- |
+| `add_shell(name, command, ...)` | Add a classic verb under `...\shell` |
+| `add_handler(name, clsid, ...)` | Add a COM handler |
+| `unblock(name_or_clsid)` | Unblock a blocked CLSID |
+| `remove_shell(name, ...)` | Remove a classic verb |
+| `remove_handler(name, ...)` | Remove a COM handler |
+| `remove_shellnew(key_path)` | Remove an entry from the "New" submenu |
+| `block(name_or_clsid)` | Block a built-in element by CLSID |
+
+`scope`: `file`, `directory`, `background`, `folder`, `drive`, `allfiles`,
+`all`, an extension (`.zip`), a ProgID glob (`VLC.*`), or `sfa:<glob>`.
+
+Writing to `HKLM` (shared across users) requires running **as administrator**;
+otherwise the action is reported as no-permission and continues.
+
+## Examples
+
+Everything is in the [`examples/`](examples) folder:
+
+- [`examples/add.py`](examples/add.py) — add entries (open folder with VS Code,
+  PowerShell here, ...).
+- [`examples/remove.py`](examples/remove.py) — full menu cleanup.
+
+Copy one, tweak it to taste, and that's your per-PC script.
+
+## `switchmenu` command
+
+Toggle the right-click menu between the **classic** (Windows 10) and the **new**
+(Windows 11) one. Restarts Explorer to apply instantly. No administrator needed:
+everything lives under `HKEY_CURRENT_USER`.
+
+```bash
+switchmenu
+```

windowsctxmenu-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+windowsctxmenu/__init__.py,sha256=BY-eHjyWgAcw-VjZujYi9QglAIPdNlG2DKUUNB8YBYg,298
+windowsctxmenu/addmenu.py,sha256=VJen6Qfbyfo_XjbH5fUsrDt0wf5lN6uNvlMAo1eUwcU,2436
+windowsctxmenu/cli.py,sha256=rOfKoAfRjAB2pWdpPbtgb4EFDdenHVeC4v-vYeWa3BA,1556
+windowsctxmenu/contextmenu.py,sha256=lfUfDLsqMeYwHDVzgFz28ekLW99QSk3FFLE4a0bdbNU,4603
+windowsctxmenu/utils.py,sha256=rmwiAfSDgqnKbgdnI1180H_B-DHcLjRnQNo3qbN0w-A,3852
+windowsctxmenu-1.0.0.dist-info/METADATA,sha256=C8W4uibdb0phzdPN3whe_Mbs8QOU0e4Gj5N6r53iMYQ,3752
+windowsctxmenu-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+windowsctxmenu-1.0.0.dist-info/entry_points.txt,sha256=pdzgUoOa58rB-NzCs1p_hTjBK__cvv_QhI3INLHKDXU,55
+windowsctxmenu-1.0.0.dist-info/licenses/LICENSE,sha256=LCRF-AF8am3DYyFN_jELdReUsuaI3tE3OOdh11UM9XY,1096
+windowsctxmenu-1.0.0.dist-info/RECORD,,

windowsctxmenu-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

windowsctxmenu-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+switchmenu = windowsctxmenu.cli:main

windowsctxmenu-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beltrán Offerrall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.