{
    "info": {
        "author": "pwssnk",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
            "Operating System :: Microsoft :: Windows",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: Implementation :: CPython",
            "Topic :: System :: Filesystems"
        ],
        "description": "# py-usvfs\nPython bindings for the userspace virtual filesystem ([usvfs](https://github.com/ModOrganizer2/usvfs/)) library\n\n### What is usvfs?\nTo quote the devs:\n>USVFS (short for User Space Virtual File System) aims to allow windows applications to create file or directory links that are visible to only a select set of processes. It does so by using api hooking to fool file access functions into discovering/opening files that are in fact somewhere else\n\nusvfs was originally written by [TanninOne](https://github.com/TanninOne/usvfs) as a part of [ModOrganizer](https://github.com/TanninOne/modorganizer), a mod manager application for various pc games (notably Bethesda titles). Development of ModOrganizer and usvfs was continued by the [ModOrganizer2](https://github.com/ModOrganizer2) team. \nusvfs is a core component of ModOrganizer. It is what allows ModOrganizer to easily install and uninstall mods without having to constantly move gigabytes of data on disk, and what gives it control over what happens when multiple mods override the same file.\n\nHowever, usvfs was designed to also be usable as a standalone library. That's great, because this kind of functionality has a variety of interesting applications.\n\n### What is py-usvfs?\nusvfs is written in C++. It needs to be, because it needs to perform low level tasks like hooking Windows API I/O function calls and injecting processes. I saw use in usvfs for some personal projects, but I usually prefer to work in higher level languages -- Python first and foremost. py-usvfs aims to make that possible.\n\npy-usvfs is two things:\na. Python bindings for the usvfs dll functionality, in the form of a pybind11 CPython extension\nb. A Python wrapper module that provides convenient, hopefully more Pythonic abstractions for that low level functionality\n\nBasically, it's intended to allow to use usvfs in python (a) and make using it less of a pain (b).\n\n### Can I use this in a production environment?\nCan you? Well, I'm not your mother. Should you? Probably not. usvfs is finicky, not always reliable and poorly documented. py-usvfs is no different. Caveat emptor.\n\npy-usvfs is NOT properly tested. No guarantuee given that anything will work.\n\n## Requirements\nBecause usvfs works by hooking Windows API I/O function calls, it only runs on Windows machines. Consequently, py-usvfs only runs on Windows as well.\nBecuase py-usvfs exposes the functionality in `usvfs_[x86|x64].dll` via a CPython extension, it will only run on the official CPython implementation of Python. \n\nThe requirements therefore are:\n* Windows OS (win32 or win-amd64)\n* CPython 3.7.x (32-bits or 64-bits)\n\n\n## Installation\n### Install pre-built packages using pip\nPre-built Python packages are available from [PyPI](https://pypi.org/). Use pip to install.\n\n```shell\npip install py-usvfs\n```\n\nOnce installed, a Python module named `usvfs` will be available.\n\n### Build it yourself\nAlternatively, you can build the required components from source code. No detailed instructions given, but these are the basics steps:\n1. Get usvfs source code from https://github.com/ModOrganizer2/usvfs/ \n2. Build `usvfs_dll` in Release/win32 and Release/x64 configurations using MSVC\n3. Place the .dll files (`usvfs_x86.dll`, `usvfs_x64.dll`) in `python-extension/usvfs/bin`, place the .lib files (`usvfs_x86.lib`, `usvfs_x64.lib`) in `python-extension/usvfs/lib`, and place the usvfs proxy exe's (`usvfs_proxy_x64.exe`, `usvfs_proxy_x86.exe`) in `python-extension/usvfs/bin` (Note that even if you are only building for a single platform, you will alwyas need both the 32-bits and 64-bits usvfs_proxy exe's)\n4. Build `python-extension` in Release/win32 and Release/x64 configurations using MSVC\n5. Run `./build-wheels.bat` to build Python wheel packages for 64-bits and 32-bits CPython\n6. You can now install the .whl files in `dist/` using `pip install [wheelname].whl`\n\n\n## Documentation\nCurrently, no extensive documentation is available. Please refer to the source code and Python docstrings. See below for a basic usage example.\n\n\n## Basic usage\nSuppose we have the following folder structure in our current working directory, and we wish to trick a program into thinking the contents of `src/` are located at `dest/`.\n\n```\n[current working directory]/\n |\n +-- src/\n |   |-- source1.txt\n |   |-- source2.txt\n |   |\n |   +-- subfolder/\n |       |-- source3.txt\n |\n +-- dest/\n```\n\n```python\nimport usvfs\n\n# Define a virtual directory link rule\nvdir = usvfs.VirtualDirectory('src/', 'dest/')  # If a process runnning \n                                                # in the vfs tries to access\n                                                # dest/*, it will be redirected to src/*\n\n# By default, py-usvfs links directories recursively, i.e. all underlying files \n# and directories of the source directory are linked automatically\n# If this behaviour is undesired, you can unset the recursive link flag:\n# vdir.link_recursively = False\n# All link flags defined by usvfs can be set/unset in this way, but only \n# if they are relevant to the context (e.g. link_recursively is \n# only available for VirtualDirectory links, not VirtualFile links)\n\n# Define our vfs layout\nvfs_map = usvfs.Mapping()    # Create a vfs mapping. This is a collection \n                             # of virtual link rules that can be applied to the vfs\nvfs_map.link(vdir)           # Add any VirtualDirectory and/or VirtualFile rules like this\n\n# Set up the vfs\nvfs = usvfs.UserspaceVFS()   # Create a usvfs controller with default instance name and configuration\nvfs.initialize()             # Initialize it\nvfs.set_mapping(vfs_map)     # Apply mapping\n\n# Now we can start a process in the vfs using vfs.run_process(...)\n# This function takes three arguments:\n# 1. string containing executable path + any command line arguments \n# 2. (optional) string specifying a working directory\n#    the default is the current working directory of your Python program\n# 3. (optional) bool specifying if this call should block execution\n#     until the child process finished (default is True)\n\nvfs.run_process('notepad.exe')\n\n# Usvfs will launch a usvfs_proxy process with the appropriate bitness, then \n# start and inject the specified process\n# If you browse to dest/ in notepad, you should see the contents of src/\n# If you then browse to dest/ in explorer, you will see that there are actually no files there!\n\n# When you're done, be sure to clean up\nvfs.close()\n```\n\nThe Python wrapper classes hide some of the uglier usvfs wrangling in a clean, relatively easy to use API. If you want more low level access, you can call the usvfs dll (semi-)directly by accessing the functions defined in the `usvfs.dll` module.\n\n```python\nimport usvfs  # Note that you cannot import usvfs.dll directly\n\n# Access dll functions, properties, structs like this:\nusvfs.dll.LINKFLAG_MONITORCHANGES\nusvfs.dll.LogLevel\nusvfs.dll.USVFSParameters()\nusvfs.dll.CreateVFS(...)\n# etc...\n```\nThis exposes most functions, structs and properties exported by `usvfs_[x86|x64].dll` (but not the debugging stuff). The function signatures in Python are similar to those in the usvfs C++ headers, but you can pass basic Python types as arguments and you don't have to deal with buffer `wchar[]`'s. See the [usvfs header file](https://github.com/pwssnk/py-usvfs/blob/master/python-extension/usvfs/include/usvfs.h) for a list of the available functions and a (not particularly useful) explanation of what they do.\n\nThe exception here is `usvfs.dll.CreateProcessHooked()`. In C/C++ calls directly to the usvfs dll, you would have to pass a bunch of Windows API nonsense to the function and deal with Windows handles. The py-usvfs CPython extension takes care of that for you, because (a) it's convenient and (b) exposing all the required Windows API stuff to Python would be a pain. The downside is that you don't have easy access to the newly spawned process status and input/output via Windows handles.\n`CreateProcessHooked()` in py-usvfs takes two arguments: a `str` containing executable path and any command line arguments to pass to it, and a `str` with a path to the intended working directory for the new process.\n\n\n## License\n(c) 2019 pwssnk -- Code available under GPL v3 license\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/pwssnk/py-usvfs",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "py-usvfs",
        "package_url": "https://pypi.org/project/py-usvfs/",
        "platform": "",
        "project_url": "https://pypi.org/project/py-usvfs/",
        "project_urls": {
            "Homepage": "https://github.com/pwssnk/py-usvfs"
        },
        "release_url": "https://pypi.org/project/py-usvfs/0.2.0/",
        "requires_dist": null,
        "requires_python": ">=3.7",
        "summary": "Python bindings for the userspace virtual filesystem (usvfs) library",
        "version": "0.2.0"
    },
    "last_serial": 5507874,
    "releases": {
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "01c6e9b67d20ade178a5805bd5da5f09",
                    "sha256": "e28a4cc98d991ab79bde05ae12ff8d4b4fd2368cd9ea8ba0dd1f2492c4b2b95d"
                },
                "downloads": -1,
                "filename": "py_usvfs-0.2.0-cp37-none-win32.whl",
                "has_sig": false,
                "md5_digest": "01c6e9b67d20ade178a5805bd5da5f09",
                "packagetype": "bdist_wheel",
                "python_version": "cp37",
                "requires_python": ">=3.7",
                "size": 1707131,
                "upload_time": "2019-07-09T15:57:01",
                "url": "https://files.pythonhosted.org/packages/05/bf/78bb4ad7eb2d5d4955693f24bb44bd7d1370a04db143430dfdf16dcc204e/py_usvfs-0.2.0-cp37-none-win32.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2a098d6db842dde353cc4b4b4392f2f7",
                    "sha256": "e98b4d143894d505925c37c47635f68fc0430c4c0eb3849ca5c35e94ae0a9584"
                },
                "downloads": -1,
                "filename": "py_usvfs-0.2.0-cp37-none-win_amd64.whl",
                "has_sig": false,
                "md5_digest": "2a098d6db842dde353cc4b4b4392f2f7",
                "packagetype": "bdist_wheel",
                "python_version": "cp37",
                "requires_python": ">=3.7",
                "size": 2476568,
                "upload_time": "2019-07-09T15:57:05",
                "url": "https://files.pythonhosted.org/packages/4e/1e/984c8a23f8d572366c9d2994d95fef7e2693ec43b4afb003c3e3c63d9d47/py_usvfs-0.2.0-cp37-none-win_amd64.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "01c6e9b67d20ade178a5805bd5da5f09",
                "sha256": "e28a4cc98d991ab79bde05ae12ff8d4b4fd2368cd9ea8ba0dd1f2492c4b2b95d"
            },
            "downloads": -1,
            "filename": "py_usvfs-0.2.0-cp37-none-win32.whl",
            "has_sig": false,
            "md5_digest": "01c6e9b67d20ade178a5805bd5da5f09",
            "packagetype": "bdist_wheel",
            "python_version": "cp37",
            "requires_python": ">=3.7",
            "size": 1707131,
            "upload_time": "2019-07-09T15:57:01",
            "url": "https://files.pythonhosted.org/packages/05/bf/78bb4ad7eb2d5d4955693f24bb44bd7d1370a04db143430dfdf16dcc204e/py_usvfs-0.2.0-cp37-none-win32.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "2a098d6db842dde353cc4b4b4392f2f7",
                "sha256": "e98b4d143894d505925c37c47635f68fc0430c4c0eb3849ca5c35e94ae0a9584"
            },
            "downloads": -1,
            "filename": "py_usvfs-0.2.0-cp37-none-win_amd64.whl",
            "has_sig": false,
            "md5_digest": "2a098d6db842dde353cc4b4b4392f2f7",
            "packagetype": "bdist_wheel",
            "python_version": "cp37",
            "requires_python": ">=3.7",
            "size": 2476568,
            "upload_time": "2019-07-09T15:57:05",
            "url": "https://files.pythonhosted.org/packages/4e/1e/984c8a23f8d572366c9d2994d95fef7e2693ec43b4afb003c3e3c63d9d47/py_usvfs-0.2.0-cp37-none-win_amd64.whl"
        }
    ]
}