{
    "content": [
        {
            "type": "text",
            "text": "# shutil (pydoc)\n\n**Summary:** shutil - Utility functions for copying and archiving files and directory trees.\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **MODULE REFERENCE** (8 lines)\n- **DESCRIPTION** (2 lines)\n- **CLASSES** (6 lines) — 4 subsections\n  - class Error (85 lines)\n  - class ExecError (87 lines)\n  - class SameFileError (88 lines)\n  - class SpecialFileError (88 lines)\n- **FUNCTIONS** (1 lines) — 22 subsections\n  - chown (5 lines)\n  - copy (10 lines)\n  - copy2 (10 lines)\n  - copyfile (5 lines)\n  - copyfileobj (2 lines)\n  - copymode (6 lines)\n  - copystat (11 lines)\n  - copytree (38 lines)\n  - disk_usage (5 lines)\n  - get_archive_formats (4 lines)\n  - get_terminal_size (18 lines)\n  - get_unpack_formats (5 lines)\n  - ignore_patterns (5 lines)\n  - make_archive (16 lines)\n  - move (24 lines)\n  - register_archive_format (8 lines)\n  - register_unpack_format (15 lines)\n  - rmtree (9 lines)\n  - unpack_archive (17 lines)\n  - unregister_archive_format (1 lines)\n  - unregister_unpack_format (2 lines)\n  - which (8 lines)\n- **DATA** (2 lines)\n- **FILE** (3 lines)\n\n## Full Content\n\n### NAME\n\nshutil - Utility functions for copying and archiving files and directory trees.\n\n### MODULE REFERENCE\n\nhttps://docs.python.org/3.10/library/shutil.html\n\nThe following documentation is automatically generated from the Python\nsource files.  It may be incomplete, incorrect or include features that\nare considered implementation detail and may vary between Python\nimplementations.  When in doubt, consult the module reference at the\nlocation listed above.\n\n### DESCRIPTION\n\nXXX The functions here don't copy the resource fork or other metadata on Mac.\n\n### CLASSES\n\nbuiltins.OSError(builtins.Exception)\nError\nSameFileError\nExecError\nSpecialFileError\n\n#### class Error\n\n|  Method resolution order:\n|      Error\n|      builtins.OSError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Data descriptors defined here:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.OSError:\n|\n|  init(self, /, *args, kwargs)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  str(self, /)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.OSError:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.OSError:\n|\n|  characterswritten\n|\n|  errno\n|      POSIX exception code\n|\n|  filename\n|      exception filename\n|\n|  filename2\n|      second exception filename\n|\n|  strerror\n|      exception strerror\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n\n#### class ExecError\n\n|  Raised when a command could not be executed\n|\n|  Method resolution order:\n|      ExecError\n|      builtins.OSError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Data descriptors defined here:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.OSError:\n|\n|  init(self, /, *args, kwargs)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  str(self, /)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.OSError:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.OSError:\n|\n|  characterswritten\n|\n|  errno\n|      POSIX exception code\n|\n|  filename\n|      exception filename\n|\n|  filename2\n|      second exception filename\n|\n|  strerror\n|      exception strerror\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n\n#### class SameFileError\n\n|  Raised when source and destination are the same file.\n|\n|  Method resolution order:\n|      SameFileError\n|      Error\n|      builtins.OSError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Data descriptors inherited from Error:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.OSError:\n|\n|  init(self, /, *args, kwargs)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  str(self, /)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.OSError:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.OSError:\n|\n|  characterswritten\n|\n|  errno\n|      POSIX exception code\n|\n|  filename\n|      exception filename\n|\n|  filename2\n|      second exception filename\n|\n|  strerror\n|      exception strerror\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n\n#### class SpecialFileError\n\n|  Raised when trying to do a kind of operation (e.g. copying) which is\n|  not supported on a special file (e.g. a named pipe)\n|\n|  Method resolution order:\n|      SpecialFileError\n|      builtins.OSError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Data descriptors defined here:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.OSError:\n|\n|  init(self, /, *args, kwargs)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  str(self, /)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.OSError:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.OSError:\n|\n|  characterswritten\n|\n|  errno\n|      POSIX exception code\n|\n|  filename\n|      exception filename\n|\n|  filename2\n|      second exception filename\n|\n|  strerror\n|      exception strerror\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n\n### FUNCTIONS\n\n#### chown\n\nChange owner user and group of the given path.\n\nuser and group can be the uid/gid or the user/group names, and in that case,\nthey are converted to their respective uid/gid.\n\n#### copy\n\nCopy data and mode bits (\"cp src dst\"). Return the file's destination.\n\nThe destination may be a directory.\n\nIf followsymlinks is false, symlinks won't be followed. This\nresembles GNU's \"cp -P src dst\".\n\nIf source and destination are the same file, a SameFileError will be\nraised.\n\n#### copy2\n\nCopy data and metadata. Return the file's destination.\n\nMetadata is copied with copystat(). Please see the copystat function\nfor more information.\n\nThe destination may be a directory.\n\nIf followsymlinks is false, symlinks won't be followed. This\nresembles GNU's \"cp -P src dst\".\n\n#### copyfile\n\nCopy data from src to dst in the most efficient way possible.\n\nIf followsymlinks is not set and src is a symbolic link, a new\nsymlink will be created instead of copying the file it points to.\n\n#### copyfileobj\n\ncopy data from file-like object fsrc to file-like object fdst\n\n#### copymode\n\nCopy mode bits from src to dst.\n\nIf followsymlinks is not set, symlinks aren't followed if and only\nif both `src` and `dst` are symlinks.  If `lchmod` isn't available\n(e.g. Linux) this method does nothing.\n\n#### copystat\n\nCopy file metadata\n\nCopy the permission bits, last access time, last modification time, and\nflags from `src` to `dst`. On Linux, copystat() also copies the \"extended\nattributes\" where possible. The file contents, owner, and group are\nunaffected. `src` and `dst` are path-like objects or path names given as\nstrings.\n\nIf the optional flag `followsymlinks` is not set, symlinks aren't\nfollowed if and only if both `src` and `dst` are symlinks.\n\n#### copytree\n\nRecursively copy a directory tree and return the destination directory.\n\nIf exception(s) occur, an Error is raised with a list of reasons.\n\nIf the optional symlinks flag is true, symbolic links in the\nsource tree result in symbolic links in the destination tree; if\nit is false, the contents of the files pointed to by symbolic\nlinks are copied. If the file pointed by the symlink doesn't\nexist, an exception will be added in the list of errors raised in\nan Error exception at the end of the copy process.\n\nYou can set the optional ignoredanglingsymlinks flag to true if you\nwant to silence this exception. Notice that this has no effect on\nplatforms that don't support os.symlink.\n\nThe optional ignore argument is a callable. If given, it\nis called with the `src` parameter, which is the directory\nbeing visited by copytree(), and `names` which is the list of\n`src` contents, as returned by os.listdir():\n\ncallable(src, names) -> ignorednames\n\nSince copytree() is called recursively, the callable will be\ncalled once for each directory that is copied. It returns a\nlist of names relative to the `src` directory that should\nnot be copied.\n\nThe optional copyfunction argument is a callable that will be used\nto copy each file. It will be called with the source path and the\ndestination path as arguments. By default, copy2() is used, but any\nfunction that supports the same signature (like copy()) can be used.\n\nIf dirsexistok is false (the default) and `dst` already exists, a\n`FileExistsError` is raised. If `dirsexistok` is true, the copying\noperation will continue if it encounters existing directories, and files\nwithin the `dst` tree will be overwritten by corresponding files from the\n`src` tree.\n\n#### disk_usage\n\nReturn disk usage statistics about the given path.\n\nReturned value is a named tuple with attributes 'total', 'used' and\n'free', which are the amount of total, used and free space, in bytes.\n\n#### get_archive_formats\n\nReturns a list of supported formats for archiving and unarchiving.\n\nEach element of the returned sequence is a tuple (name, description)\n\n#### get_terminal_size\n\nGet the size of the terminal window.\n\nFor each of the two dimensions, the environment variable, COLUMNS\nand LINES respectively, is checked. If the variable is defined and\nthe value is a positive integer, it is used.\n\nWhen COLUMNS or LINES is not defined, which is the common case,\nthe terminal connected to sys.stdout is queried\nby invoking os.getterminalsize.\n\nIf the terminal size cannot be successfully queried, either because\nthe system doesn't support querying, or because we are not\nconnected to a terminal, the value given in fallback parameter\nis used. Fallback defaults to (80, 24) which is the default\nsize used by many terminal emulators.\n\nThe value returned is a named tuple of type os.terminalsize.\n\n#### get_unpack_formats\n\nReturns a list of supported formats for unpacking.\n\nEach element of the returned sequence is a tuple\n(name, extensions, description)\n\n#### ignore_patterns\n\nFunction that can be used as copytree() ignore parameter.\n\nPatterns is a sequence of glob-style patterns\nthat are used to exclude files\n\n#### make_archive\n\nCreate an archive file (eg. zip or tar).\n\n'basename' is the name of the file to create, minus any format-specific\nextension; 'format' is the archive format: one of \"zip\", \"tar\", \"gztar\",\n\"bztar\", or \"xztar\".  Or any other registered format.\n\n'rootdir' is a directory that will be the root directory of the\narchive; ie. we typically chdir into 'rootdir' before creating the\narchive.  'basedir' is the directory where we start archiving from;\nie. 'basedir' will be the common prefix of all files and\ndirectories in the archive.  'rootdir' and 'basedir' both default\nto the current directory.  Returns the name of the archive file.\n\n'owner' and 'group' are used when creating a tar archive. By default,\nuses the current owner and group.\n\n#### move\n\nRecursively move a file or directory to another location. This is\nsimilar to the Unix \"mv\" command. Return the file or directory's\ndestination.\n\nIf the destination is a directory or a symlink to a directory, the source\nis moved inside the directory. The destination path must not already\nexist.\n\nIf the destination already exists but is not a directory, it may be\noverwritten depending on os.rename() semantics.\n\nIf the destination is on our current filesystem, then rename() is used.\nOtherwise, src is copied to the destination and then removed. Symlinks are\nrecreated under the new name if os.rename() fails because of cross\nfilesystem renames.\n\nThe optional `copyfunction` argument is a callable that will be used\nto copy the source or it will be delegated to `copytree`.\nBy default, copy2() is used, but any function that supports the same\nsignature (like copy()) can be used.\n\nA lot more could be done here...  A look at a mv.c shows a lot of\nthe issues this implementation glosses over.\n\n#### register_archive_format\n\nRegisters an archive format.\n\nname is the name of the format. function is the callable that will be\nused to create archives. If provided, extraargs is a sequence of\n(name, value) tuples that will be passed as arguments to the callable.\ndescription can be provided to describe the format, and will be returned\nby the getarchiveformats() function.\n\n#### register_unpack_format\n\nRegisters an unpack format.\n\n`name` is the name of the format. `extensions` is a list of extensions\ncorresponding to the format.\n\n`function` is the callable that will be\nused to unpack archives. The callable will receive archives to unpack.\nIf it's unable to handle an archive, it needs to raise a ReadError\nexception.\n\nIf provided, `extraargs` is a sequence of\n(name, value) tuples that will be passed as arguments to the callable.\ndescription can be provided to describe the format, and will be returned\nby the getunpackformats() function.\n\n#### rmtree\n\nRecursively delete a directory tree.\n\nIf ignoreerrors is set, errors are ignored; otherwise, if onerror\nis set, it is called to handle the error with arguments (func,\npath, excinfo) where func is platform and implementation dependent;\npath is the argument to that function that caused it to fail; and\nexcinfo is a tuple returned by sys.excinfo().  If ignoreerrors\nis false and onerror is None, an exception is raised.\n\n#### unpack_archive\n\nUnpack an archive.\n\n`filename` is the name of the archive.\n\n`extractdir` is the name of the target directory, where the archive\nis unpacked. If not provided, the current working directory is used.\n\n`format` is the archive format: one of \"zip\", \"tar\", \"gztar\", \"bztar\",\nor \"xztar\".  Or any other registered format.  If not provided,\nunpackarchive will use the filename extension and see if an unpacker\nwas registered for that extension.\n\nIn case none is found, a ValueError is raised.\n\nIf `filter` is given, it is passed to the underlying\nextraction function.\n\n#### unregister_archive_format\n\n#### unregister_unpack_format\n\nRemoves the pack format from the registry.\n\n#### which\n\nGiven a command, mode, and a PATH string, return the path which\nconforms to the given mode on the PATH, or None if there is no such\nfile.\n\n`mode` defaults to os.FOK | os.XOK. `path` defaults to the result\nof os.environ.get(\"PATH\"), or can be overridden with a custom search\npath.\n\n### DATA\n\nall = ['copyfileobj', 'copyfile', 'copymode', 'copystat', 'copy', ...\n\n### FILE\n\n/usr/lib/python3.10/shutil.py\n\n"
        }
    ],
    "structuredContent": {
        "command": "shutil",
        "section": "",
        "mode": "pydoc",
        "summary": "shutil - Utility functions for copying and archiving files and directory trees.",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "MODULE REFERENCE",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "CLASSES",
                "lines": 6,
                "subsections": [
                    {
                        "name": "class Error",
                        "lines": 85
                    },
                    {
                        "name": "class ExecError",
                        "lines": 87
                    },
                    {
                        "name": "class SameFileError",
                        "lines": 88
                    },
                    {
                        "name": "class SpecialFileError",
                        "lines": 88
                    }
                ]
            },
            {
                "name": "FUNCTIONS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "chown",
                        "lines": 5
                    },
                    {
                        "name": "copy",
                        "lines": 10
                    },
                    {
                        "name": "copy2",
                        "lines": 10
                    },
                    {
                        "name": "copyfile",
                        "lines": 5
                    },
                    {
                        "name": "copyfileobj",
                        "lines": 2
                    },
                    {
                        "name": "copymode",
                        "lines": 6
                    },
                    {
                        "name": "copystat",
                        "lines": 11
                    },
                    {
                        "name": "copytree",
                        "lines": 38
                    },
                    {
                        "name": "disk_usage",
                        "lines": 5
                    },
                    {
                        "name": "get_archive_formats",
                        "lines": 4
                    },
                    {
                        "name": "get_terminal_size",
                        "lines": 18
                    },
                    {
                        "name": "get_unpack_formats",
                        "lines": 5
                    },
                    {
                        "name": "ignore_patterns",
                        "lines": 5
                    },
                    {
                        "name": "make_archive",
                        "lines": 16
                    },
                    {
                        "name": "move",
                        "lines": 24
                    },
                    {
                        "name": "register_archive_format",
                        "lines": 8
                    },
                    {
                        "name": "register_unpack_format",
                        "lines": 15
                    },
                    {
                        "name": "rmtree",
                        "lines": 9
                    },
                    {
                        "name": "unpack_archive",
                        "lines": 17
                    },
                    {
                        "name": "unregister_archive_format",
                        "lines": 1
                    },
                    {
                        "name": "unregister_unpack_format",
                        "lines": 2
                    },
                    {
                        "name": "which",
                        "lines": 8
                    }
                ]
            },
            {
                "name": "DATA",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "FILE",
                "lines": 3,
                "subsections": []
            }
        ]
    }
}