I&g5dZddlZddlZddlZddlZddlmZddlZddl Z ddl Z ddl m Z ddlZddlZddlZddlZdZdZdZeZej0dZd ZGd d eZGd d eZ ddZy)z An object-oriented file access library for Python. More module documentation to come soon. For now, take a look at the File class to see what it does. Issues should be filed at http://github.com/javawizard/fileutils/issues. N)closing)partialskiprecurseyieldc>tD]}|jdy)NT)ignore_missing)_delete_on_exitdeletefs X/mounts/lovelace/software/anaconda3/envs/py312/lib/python3.12/site-packages/fileutils.py_r$s & %&c| t|Sy)zL Returns File(f), unless f is None, in which case None is returned. N)Filer s r file_or_noner*s }AwrceZdZdZdZedZedZedZedZ edZ edZ ed Z d Z d Zed Zd ZedZdZdZdZeZdZdZdZedZdHdZedZedZdIdZedZdJdZedZ dHdZ!dHdZ"dHd Z#dKd"Z$ed#Z%d$Z&d%Z'dLd&Z(dLd'Z)dLd(Z*dMd)Z+e,jZd!fd*Z.dHd+Z/dHd,Z0dHd-Z1dNd.Z2d/Z3d0Z4ed1Z5dLd2Z6d3Z7dNd4Z8dHd5Z9dJd6Z:dHd7Z;dHd8ZdHd;Z?ed<Z@e@jd=Z@d>ZBd?ZCdJd@ZDdAZEdBZFdLdCZGdDZHeHZIdEZJdFZKdGZLy)Ora  An object representing a file or folder. File objects are intended to be as opaque as possible; one should rarely, if ever, need to know about the pathname of a File object, or that a File even has a pathname associated with it. The file or folder referred to by a File object need not exist. One can test whether a File object represents a file that does exist using the exists property. File objects cannot be changed to refer to a different file after they are created. c|r#t|dtr|dj}n!|rtjj |}nd}tjj |}||_y)a Creates a new file from the specified path components. Each component represents the name of a folder or a file. These are internally joined as if by os.path.join(*path_components). It's also possible, although not recommended, to pass a full pathname (in the operating system's native format) into File. On Windows, one could therefore do File(r"C:\some\file"), and File("/some/file") on Linux and other Unix operating systems. You can also call File(File(...)). This is equivalent to File(...) and exists to make it easier for functions to accept either a pathname or a File object. Passing no arguments (i.e. File()) results in a file that refers to the working directory as of the time the File instance was constructed. Pathnames are internally stored in absolute form; as a result, changing the working directory after creating a File instance will not change the file referred to. rN) isinstancer_pathospathjoinabspath)selfpath_componentsrs r__init__z File.__init__BsX. z/!*BGGNN4::$> >>rcTtjj|jS)z True if this file/folder exists, False if it doesn't. This will be True even for broken symbolic links; use self.valid if you want an alternative that returns False for broken symbolic links. )rrlexistsrr"s rr-z File.existsswwtzz**rcTtjj|jS)z True if this file/folder exists, False if it doesn't. This will be False for broken symbolic links; use self.exists if you want an alternative that returns True for broken symbolic links. )rrr-rr"s rvalidz File.validsww~~djj))rcL|jstd|jzy)zy Checks to see whether this File refers to a folder. If it doesn't, an exception will be thrown. z)"%s" does not exist or is not a directoryN)r# Exceptionrr"s r check_folderzFile.check_folders% ~~G$**TU UrcL|jstd|jzy)zw Checks to see whether this File refers to a file. If it doesn't, an exception will be thrown. z$"%s" does not exist or is not a fileN)r(r4rr"s r check_filezFile.check_files% ||BTZZOP Prcx|jsy|jDcgc]}|j|c}Scc}w)z A list of all of the children of this file, as a list of File objects. If this file is not a folder, the value of this property is None. N)r# child_nameschild)rps rchildrenz File.childrens0 ~~ '+'7'78! 1 888s7c|jS)zG An obsolete method that simply returns self.children. )r<r"s rlistz File.lists}}rcl|jsyttj|jS)z A list of the names of all of the children of this file, as a list of strings. If this file is not a folder, the value of this property is None. N)r#sortedrlistdirrr"s rr9zFile.child_namess&~~ bjj,--rc|jS)zJ An obsolete method that simply returns self.child_names. )r9r"s r list_nameszFile.list_namessrc4t|jg|i|S)z Opens the file referred to by this File object and returns a Python file instance. *args and **kwargs are passed through to Python's open function as if by open(self.path, *args, **kwargs). )openr)rargskwargss rrEz File.opens DJJ0000rchttjj|jg|S)a7 Returns a File object representing the child of this file with the specified name. If multiple names are present, they will be joined together. If no names are present, self will be returned. If any names are absolute, all names before them (and self) will be discarded. Relative names (like "..") are also allowed. If you want a method that guarantees that the result is a child of self, use self.safe_child(...). This method is analogous to os.path.join(self.path, *names). )rrrr)rnamess rr:z File.childs%BGGLL3U344rctjtjj |j|Dcgc] }t |c}Scc}w)z Expands the specified path relative to self and returns a list of all matching files, as File objects. This is a thin wrapper around a call to Python's glob.glob function. )_globglobrrrr)rrLr s rrLz File.globs8 "'BGGLLD,I!JKAQKKKsAch|j|}|j|std|d||S)a Same as self.child(*names), but checks that the resulting file is a descendant of self. If it's not, an exception will be thrown. This allows unsanitized paths to be used without fear that things like ".." will be used to escape the confines of self. The pathname may contain occurrences of ".." so long as they do not escape self. For example, "a/b/../c" is perfectly fine, but "a/../.." is not. zNames z escape the parent )r: ancestor_of ValueError)rrIr:s r safe_childzFile.safe_childs7 E"&tLM M rc8|jj|S)z Returns a File object representing the sibling of this file with the specified name. This is equivalent to self.parent.child(name). )parentr:rnames rsiblingz File.siblings {{  &&rctjj|j}||dk(ryt |}||k(ry|S)z Returns a File representing the parent of this file. If this file has no parent (for example, if it's "/" on Unix-based operating systems or a drive letter on Windows), None will be returned. Nr)rrdirnamerr)rrWr s rrRz File.parent sB''//$**- ?gm M 9rcp|r|}n |j}g}| |j||j}| |S)z Returns a list of all of the ancestors of this file, with self.parent first. If including_self is True, self will be first, self.parent will be second, and so on. )rRappend)rincluding_selfcurrentresultss r get_ancestorszFile.get_ancestorssD GkkG! NN7 #nnG!rc"|jS)a A list of all of the ancestors of this file, with self.parent first. This property simply returns self.get_ancestors(). Have a look at that method if you need to do more complex things like include self as one of the returned ancestors. )r]r"s r ancestorszFile.ancestors.s!!##rcTtjj|jS)z The name of this file. For example, File("a", "b", "c").name will be "c". On Unix-based operating systems, File("/").name will be the empty string. )rrbasenamerr"s rrTz File.name9sww ++rNcz|tjj}|j|j |S)a Gets the path to the file represented by this File object. If relative_to is specified, the returned path will be a relative path, the path of this file relative to the specified one. Otherwise, the returned path will be absolute. If separator (which must be a string) is specified, it will be used as the separator to place between path components in the returned path. Otherwise, os.path.sep will be used as the separator. )rrseprget_path_components)r relative_to separators rget_pathz File.get_pathDs1   I~~d66{CDDrc"|jS)a The absolute path to the file represented by this File object, in a format native to the operating system in use. This pathname can then be used with Python's traditional file-related utilities. This property simply returns self.get_path(). See the documentation for that method for more complex ways of creating paths (including obtaining relative paths). )rgr"s rrz File.pathTs}}rc |3|jjtjjStjj |jt |jjtjS)a Returns a list of the components in this file's path, including (on POSIX-compliant systems) an empty leading component for absolute paths. If relative_to is specified, the returned set of components will represent a relative path, the path of this file relative to the specified one. Otherwise, the returned components will represent an absolute path. )rsplitrrrcrelpathrrres rrdzFile.get_path_componentsasZ  ::##BGGKK0 077??4::tK/@/F/FGMMbffU Urc"|jS)zL A property that simply returns self.get_path_components(). )rdr"s rrzFile.path_componentsps ''))rc t|}|j|jr|std|z|j d5}|j D]}|j | dddy#1swYyxYw)a7 Copies the contents of this file to the specified File object or pathname. An exception will be thrown if the specified file already exists and overwrite is False. This does not currently work for folders; I hope to add this ability in the near future. %r already existswbN)rr7r-r4rE read_blockswrite)rother overwritewrite_toblocks rcopy_toz File.copy_towsxU   << /%78 8 ZZ  &))+ &u% & & & &s 'A::BcZ|j|j|j|y)a Copies this file to an identically named file inside the specified folder. This is just shorthand for self.copy_to(other.child(self.name)) which, from experience, seems to be by far the most common use case for the copy_to function. N)rwr:rT)rrsrts r copy_intozFile.copy_intos U[[+Y7rc|jr|std|ztj|}|j d5}t j ||dddy#1swYyxYw)z Downloads the specified URL and saves it to self. If self already exists and overwrite is False, an exception will be thrown; otherwise, self will be overwritten. rorpN)r-r4urllib2urlopenrEshutil copyfileobj)rurlrtsr s r download_fromzFile.download_froms^ ;;y/$67 7 OOC  YYt_ %   q! $ % % %s A##A,Tc#K|dn||}|tdfvr|r||tdfvs|r5|s2|jxsgD]}|j|d|D]}| yyyw)a A generator that recursively yields all child File objects of this file. Files and directories (and the files and directories contained within them, and so on) are all included. A filter function accepting one argument can be specified. It will be called for each file and folder. It can return one of True, False, SKIP, YIELD, or RECURSE, with the behavior of each outlined in the following table: Don't yield Do yield +-------------+----------+ Don't recurse into | SKIP | YIELD | +-------------+----------+ Do recurse into | RECURSE | True | +-------------+----------+ False behaves the same as RECURSE if recurse_skipped is True, or SKIP otherwise. If include_self is True (the default), this file (a.k.a. self) will be yielded as well (if it matches the specified filter function). If it's False, only this file's children (and their children, and so on) will be yielded. NT)YIELDRECURSEr<r)rfilter include_selfrecurse_skippedincluder:r s rrz File.recurses|4!.$fTl udm # J wo %/'," vt_EAG CJ/sAA!c|jrtd|jDS|jr)tj j |jSy)a The size, in bytes, of this file. This is the number of bytes that the file contains; the number of actual bytes of disk space it consumes is usually larger. If this file is actually a folder, the sizes of its child files and folders will be recursively summed up and returned. This can take quite some time for large folders. This is the same as len(self). c34K|]}|jywNsize).0r s r zFile.size..s5!qvv5sr)r#sumr<r(rrgetsizerr"s rrz File.sizesA >>5t}}55 5 \\77??4::. .rc|jSrrr"s r__len__z File.__len__s yyrcjtj|jt|jy)zu Rename this file or folder to the specified name, which can be a File object or a pathname. N)rrenamerrrrrss r rename_tozFile.rename_tos $**d5k../rc~|jd|rdndz5}|jcdddS#1swYyxYw)ak Read the contents of this file and return them as a string. This is usually a bad idea if the file in question is large, as the entire contents of the file will be loaded into memory. If binary is True (the default), the file will be read byte-for-byte. If it's False, the file will be read in text mode. rbrNrEread)rbinaryr s rrz File.reads9YYsVc4 5 668   s3<c|jd|rdndz5}|j|dddy#1swYyxYw)a Overwrite this file with the specified data. After this is called, self.size will be equal to len(data), and self.read() will be equal to data. If you want to append data instead, use self.append(). If binary is True (the default), the file will be written byte-for-byte. If it's False, the file will be written in text mode. wrrNrErrrdatarr s rrrz File.writes;YYsVc4 5  GGDM   4=c|jd|rdndz5}|j|dddy#1swYyxYw)z Append the specified data to the end of this file. If binary is True (the default), the file will be appended to byte-for-byte. If it's False, the file will be appended to in text mode. arrNrrs rrYz File.appends;YYsVc4 5  GGDM   rc#K|jd|rdndz5}|j|}|r||j|}|rdddy#1swYyxYww)a A generator that yields successive blocks of data from this file. Each block will be no larger than block_size bytes, which defaults to 16384. This is useful when reading/processing files larger than would otherwise fit into memory. One could implement, for example, a copy function thus: with target.open("wb") as target_stream: for block in source.read_blocks(): target_stream.write(block) rrrNr)r block_sizerr rs rrqzFile.read_blockss\YYsVc4 5 *66*%D vvj) * * *sA+A AAAc|}|jd5}tt|jddD]}|j | ddd|r|j }|S#1swYxYw)a Compute the hash of this file and return it, as a hexidecimal string. The default algorithm is md5. An alternate constructor from hashlib can be passed as the algorithm parameter; file.hash(hashlib.sha1) would, for example, compute the SHA-1 hash instead. If return_hex is False (it defaults to True), the hash object itself will be returned instead of the return value of its hexdigest() method. One can use this to access the binary hash instead. rb rN)rEiter_partialrupdate hexdigest)r algorithm return_hexhasherr rvs rhashz File.hashsr YYt_ %hqvvr2B7 % e$ % % %%'F  % %s 7A--A6c(|j|y)z An obsolete alias for self.create_folder(ignore_existing=silent) present for backward compatibility reasons. )ignore_existingN create_folderrsilents rmkdirz File.mkdir's 62rc*|j|dyz An obsolete alias for self.create_folder(ignore_existing=silent, recursive=True) present for backward compatibility reasons. T)r recursiveNrrs rmkdirsz File.mkdirs. 6TBrc*|j|dyrrrs rmakedirsz File.makedirs5rrc|jr|rytd|jz|r>|jr2|jjs|jj dt j|jy)aE Creates the folder referred to by this File object. If it already exists but is not a folder, an exception will be thrown. If it already exists and is a folder, an exception will be thrown if ignore_existing is False (the default); if ignore_existing is True, no exception will be thrown. If the to-be-created folder's parent does not exist and recursive is False, an exception will be thrown. If recursive is True, the folder's parent, its parent's parent, and so on will be created automatically. NzThe folder %r already exists.Tr)r#r4rrRr-rrr)rrrs rrzFile.create_folder<sd >> ?$)) KLL T[[1C1C ))D)9 HHTYY rcBtj|jy)am Sets the current working directory to self. Since File instances internally store paths in absolute form, other File instances will continue to work just fine after this is called. If you need to restore the working directory at any point, you might want to consider using self.as_working instead. N)rchdirrr"s r change_tozFile.change_toZs rc$|jy)z0 An alias for self.change_to(). N)rr"s rcdzFile.cdfs rct|S)a A property that returns a context manager. This context manager sets the working directory to self upon being entered and restores it to what it previously was upon being exited. One can use this to replace something like: old_dir = File() new_dir.cd() try: ...stuff... finally: old_dir.cd() with the much nicer: with new_dir.as_working: ...stuff... and get exactly the same effect. The context manager's __enter__ returns self (this file), so you can also use an "as" clause on the with statement to get access to the file in case you haven't got it stored in a variable anywhere. ) _AsWorkingr"s r as_workingzFile.as_workingls4$rcTttjt|jd5}|j D]M}|r|j |}n|j |j}|j|j|O dddy#1swYyxYw)a. Creates a zip archive of this folder and writes it to the specified filename, which can be either a pathname or a File object. If contents is True (the default), the files (and folders, and so on recursively) contained within this folder will be written directly to the zip file. If it's False, the folder will be written itself. The difference is that, given a folder foo which looks like this: foo/ bar baz/ qux Specifying contents=False will result in a zip file whose contents look something like: zipfile.zip/ foo/ bar baz/ qux Whereas specifying contents=True will result in this: zipfile.zip/ bar baz/ qux NOTE: This has only been tested on Linux. I still need to test it on Windows to make sure pathnames are being handled correctly. rN) r zip_moduleZipFilerrr relative_pathrRrr)rfilenamecontentszipfiler path_in_zips rzip_intoz File.zip_intosDZ''X(;(;SA B 3g\\^ 3"#//$"7K"#//$++">K affk2  3 3 3 3s A!BB'ct|}|jdttj|j d5}|j |jdddy#1swYyxYw)av Unzips the zip file referred to by self into the specified folder, which will be automatically created (as if by File(folder).mkdirs()) if it does not yet exist. NOTE: This is an unsafe operation! The same warning present on Python's zipfile.ZipFile.extractall applies here, namely that a maliciously crafted zip file could cause absolute filesystem paths to be overwritten. I hope to hand-roll my own extraction code in the future that will explicitly filter out absolute paths. The return value of this function is File(folder). T)rrN)rrrrrr extractallr)rfolderrs r unzip_intozFile.unzip_intos]f T " Z'' C8 9 ,W   v{{ + , , ,s A,,A5c(|js|s tdy|jrM|jsA|jD]}|j t j|jyt j|jy)a  Deletes this file or folder, recursively deleting children if necessary. The contents parameter has no effect, and is present for backward compatibility. If the file does not exist and ignore_missing is False, an exception will be thrown. If the file does not exist but ignore_missing is True, this function simply does nothing. Note that symbolic links are never recursed into, and are instead themselves removed. zThis file does not exist.N) r-r4r#r+r<r rrmdirrremover)rrr r:s rr z File.deletesh{{! ;<<" ^^DLL    HHTYY  IIdjj !rc&|j|y)z This has been merged into the delete method and as such should no longer be used. It has the exact same effect as delete. N)r )rrs r delete_folderzFile.delete_folders Hrc<| t}|j|S)z An obsolete alias for self.get_path(relative_to=...), except that, if relative_to is None, the working directory will be used instead. )rrgrls rrzFile.relative_paths  &K}}[))rc:|t|j|vS)a Returns true if this file is an ancestor of the specified file. A file is an ancestor of another file if that other file's parent is this file, or its parent's parent is this file, and so on. If including_self is True, the file is considered to be an ancestor of itself, i.e. True will be returned in the case that self == other. Otherwise, only the file's immediate parent, and its parent's parent, and so on are considered to be ancestors. )rr]rrsrZs rrNzFile.ancestor_ofstE{00@@@rc8t|j||S)z Returns true if this file is a descendant of the specified file. This is equivalent to File(other).ancestor_of(self, including_self). )rrNrs r descendant_ofzFile.descendant_ofs E{&&t^< listxattrrIOErrorerrno EOPNOTSUPPENOENT)rres r list_xattrszFile.list_xattrsNs^D   23 3 ww%***agg.E   s #* A:;A5.A:4A55A:cFddl}|j|j||y)z Sets an extended attribute with the specified name and value on this file. The same compatibility warnings present on list_xattrs apply here. rN)rsetxattrr)rrTrrs r set_xattrzFile.set_xattrzs  tyy$.rc$ddl} |j|j|S#t$rd}|jtj k(s:|jtj k(s|jtjk(r|cYd}~Sd}~wwxYw)a3 Returns the value of the extended attribute with the specified name on this file, as a string, or returns the value of default (which defaults to None) if no such extended attribute exists. The same compatibility warnings present on list_xattrs apply here. rN)rgetxattrrrrENODATArr)rrTdefaultrrs r get_xattrzFile.get_xattrsj  >>$))T2 2 5==(AGGu7G7G,Gww%,,.  s!" BAB B B  Bc*|j|dduS)z Returns True if this file has an extended attribute with the specified name, or False if it doesn't. The same compatibility warnings present on list_xattrs apply here. N)rrSs r has_xattrzFile.has_xattrs~~dD)55rcddl} |j|j|S#t$r>}|jtj k(rt d|jd|d}~wwxYw)ai Same as get_xattr, but throws a KeyError if the specified extended attribute does not exist instead of returning a default value. The same compatibility warnings present on list_xattrs apply here. Note that an IOError will be thrown if extended attributes aren't supported instead of KeyError. rNzFile z has no attribute )rrrrrrKeyError)rrTrrs r check_xattrzFile.check_xattrsX  >>$))T2 2 ww%--' 4PQQ  s" A)9A$$A)c(ddl} |j|j|y#t$re}|jtj k(s:|jtj k(s|jtjk(r|rnYd}~yd}~wwxYw)a_ Deletes the extended attribute with the specified name from this file. If the attribute does not exist and silent is true, nothing will happen. If the attribute does not exist and silent is false, an exception will be thrown. The same compatibility warnings present on list_xattrs apply here. rN)r removexattrrrrrrr)rrTrrrs r delete_xattrzFile.delete_xattrsn     dii . 5==(AGGu7G7G,Gww%,,.F  s# BAB  Bc d|jzS)Nzfileutils.File(%r))rr"s r__str__z File.__str__s#djj00rct|tstSttj j |j tj j |j Sr)rrNotImplementedcmprrnormcasers r__cmp__z File.__cmp__sE%&! !277##DII.0@0@0LMMrcfttjj|jSr)rrrrr"s r__hash__z File.__hash__s BGG$$TYY/00rcy)z Returns True. File objects are always true values; to test for their existence, use self.exists instead. Tr"s r __nonzero__zFile.__nonzero__s r)F)NNr)NTT)T)i@T)FF)M__name__ __module__ __qualname____doc__rpropertyr#r%r(r+r.r-r2r5r7r<r>r9rCrEr:__div__rLrPrUrRr]r_rTrgrrdrrwryrrrrrrrrrYrqhashlibmd5rrrrrrrrrrr rrrNrrrrrsetterrrrrrr r __repr__rrrrrrrr4s  D)) ****?? ++**VQ99 .. 1 5 GL '" $$,,E    V** &"8 % D&0   *&%[[T(3CC <    6(3T,&"2* A= *'',''*** *X/&6&(1HN 1rrc"eZdZdZdZdZdZy)rz The class of the context managers returned from File.as_working. See that method's docstring for more information on what this class does. c||_yr)r)rrs rrz_AsWorking.__init__s  rctj|_|jj |jSr)rgetcwdold_pathrrr"s r __enter__z_AsWorking.__enter__s'   {{rcBtj|jyr)rrr$)rrFs r__exit__z_AsWorking.__exit__s rN)rrrrrr%r'rrrrrs  rrct|xstj}ttj|||j}||_|S)aC Creates a folder (with tmpfile.mkdtemp) with the specified prefix, suffix, and parent folder (or the current platform's default temporary directory if no parent is specified). If delete_on_exit is True, the returned file's delete_on_exit property will be set to True just before returning it. )rtempfile gettempdirmkdtemprr)suffixprefixrRrrs rcreate_temporary_folderr.sF&1H//1 2F (""666;;? @F*F Mr)rtmpNF)rros.pathr}rr contextlibrrurllibr functoolsrrrLrKr{atexitr)SKIPrrsetr registerrrobjectrrr.rrrr9s   )   %&& f6fR  "=A+0 r