Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

filepath.py 53KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609
  1. # -*- test-case-name: twisted.test.test_paths -*-
  2. # Copyright (c) Twisted Matrix Laboratories.
  3. # See LICENSE for details.
  4. """
  5. Object-oriented filesystem path representation.
  6. """
  7. import base64
  8. import errno
  9. import os
  10. import sys
  11. from os import listdir, stat, utime
  12. from os.path import (
  13. abspath,
  14. basename,
  15. dirname,
  16. exists,
  17. isabs,
  18. join as joinpath,
  19. normpath,
  20. splitext,
  21. )
  22. from stat import (
  23. S_IMODE,
  24. S_IRGRP,
  25. S_IROTH,
  26. S_IRUSR,
  27. S_ISBLK,
  28. S_ISDIR,
  29. S_ISREG,
  30. S_ISSOCK,
  31. S_IWGRP,
  32. S_IWOTH,
  33. S_IWUSR,
  34. S_IXGRP,
  35. S_IXOTH,
  36. S_IXUSR,
  37. )
  38. from typing import IO, Union, cast
  39. from zope.interface import Attribute, Interface, implementer
  40. from twisted.python.compat import cmp, comparable
  41. from twisted.python.runtime import platform
  42. from twisted.python.util import FancyEqMixin
  43. from twisted.python.win32 import (
  44. ERROR_DIRECTORY,
  45. ERROR_FILE_NOT_FOUND,
  46. ERROR_INVALID_NAME,
  47. ERROR_PATH_NOT_FOUND,
  48. O_BINARY,
  49. )
  50. # Please keep this as light as possible on other Twisted imports; many, many
  51. # things import this module, and it would be good if it could easily be
  52. # modified for inclusion in the standard library. --glyph
  53. _CREATE_FLAGS = os.O_EXCL | os.O_CREAT | os.O_RDWR | O_BINARY
  54. def _stub_islink(path):
  55. """
  56. Always return C{False} if the operating system does not support symlinks.
  57. @param path: A path string.
  58. @type path: L{str}
  59. @return: C{False}
  60. @rtype: L{bool}
  61. """
  62. return False
  63. islink = getattr(os.path, "islink", _stub_islink)
  64. randomBytes = os.urandom
  65. armor = base64.urlsafe_b64encode
  66. class IFilePath(Interface):
  67. """
  68. File path object.
  69. A file path represents a location for a file-like-object and can be
  70. organized into a hierarchy; a file path can can children which are
  71. themselves file paths.
  72. A file path has a name which unique identifies it in the context of its
  73. parent (if it has one); a file path can not have two children with the same
  74. name. This name is referred to as the file path's "base name".
  75. A series of such names can be used to locate nested children of a file
  76. path; such a series is referred to as the child's "path", relative to the
  77. parent. In this case, each name in the path is referred to as a "path
  78. segment"; the child's base name is the segment in the path.
  79. When representing a file path as a string, a "path separator" is used to
  80. delimit the path segments within the string. For a file system path, that
  81. would be C{os.sep}.
  82. Note that the values of child names may be restricted. For example, a file
  83. system path will not allow the use of the path separator in a name, and
  84. certain names (e.g. C{"."} and C{".."}) may be reserved or have special
  85. meanings.
  86. @since: 12.1
  87. """
  88. sep = Attribute("The path separator to use in string representations")
  89. def child(name):
  90. """
  91. Obtain a direct child of this file path. The child may or may not
  92. exist.
  93. @param name: the name of a child of this path. C{name} must be a direct
  94. child of this path and may not contain a path separator.
  95. @return: the child of this path with the given C{name}.
  96. @raise InsecurePath: if C{name} describes a file path that is not a
  97. direct child of this file path.
  98. """
  99. def open(mode="r"):
  100. """
  101. Opens this file path with the given mode.
  102. @return: a file-like object.
  103. @raise Exception: if this file path cannot be opened.
  104. """
  105. def changed():
  106. """
  107. Clear any cached information about the state of this path on disk.
  108. """
  109. def getsize():
  110. """
  111. Retrieve the size of this file in bytes.
  112. @return: the size of the file at this file path in bytes.
  113. @raise Exception: if the size cannot be obtained.
  114. """
  115. def getModificationTime():
  116. """
  117. Retrieve the time of last access from this file.
  118. @return: a number of seconds from the epoch.
  119. @rtype: L{float}
  120. """
  121. def getStatusChangeTime():
  122. """
  123. Retrieve the time of the last status change for this file.
  124. @return: a number of seconds from the epoch.
  125. @rtype: L{float}
  126. """
  127. def getAccessTime():
  128. """
  129. Retrieve the time that this file was last accessed.
  130. @return: a number of seconds from the epoch.
  131. @rtype: L{float}
  132. """
  133. def exists():
  134. """
  135. Check if this file path exists.
  136. @return: C{True} if the file at this file path exists, C{False}
  137. otherwise.
  138. @rtype: L{bool}
  139. """
  140. def isdir():
  141. """
  142. Check if this file path refers to a directory.
  143. @return: C{True} if the file at this file path is a directory, C{False}
  144. otherwise.
  145. """
  146. def isfile():
  147. """
  148. Check if this file path refers to a regular file.
  149. @return: C{True} if the file at this file path is a regular file,
  150. C{False} otherwise.
  151. """
  152. def children():
  153. """
  154. List the children of this path object.
  155. @return: a sequence of the children of the directory at this file path.
  156. @raise Exception: if the file at this file path is not a directory.
  157. """
  158. def basename():
  159. """
  160. Retrieve the final component of the file path's path (everything
  161. after the final path separator).
  162. @return: the base name of this file path.
  163. @rtype: L{str}
  164. """
  165. def parent():
  166. """
  167. A file path for the directory containing the file at this file path.
  168. """
  169. def sibling(name):
  170. """
  171. A file path for the directory containing the file at this file path.
  172. @param name: the name of a sibling of this path. C{name} must be a
  173. direct sibling of this path and may not contain a path separator.
  174. @return: a sibling file path of this one.
  175. """
  176. class InsecurePath(Exception):
  177. """
  178. Error that is raised when the path provided to L{FilePath} is invalid.
  179. """
  180. class LinkError(Exception):
  181. """
  182. An error with symlinks - either that there are cyclical symlinks or that
  183. symlink are not supported on this platform.
  184. """
  185. class UnlistableError(OSError):
  186. """
  187. An exception which is used to distinguish between errors which mean 'this
  188. is not a directory you can list' and other, more catastrophic errors.
  189. This error will try to look as much like the original error as possible,
  190. while still being catchable as an independent type.
  191. @ivar originalException: the actual original exception instance.
  192. """
  193. def __init__(self, originalException: OSError):
  194. """
  195. Create an UnlistableError exception.
  196. @param originalException: an instance of OSError.
  197. """
  198. self.__dict__.update(originalException.__dict__)
  199. self.originalException = originalException
  200. def _secureEnoughString(path):
  201. """
  202. Compute a string usable as a new, temporary filename.
  203. @param path: The path that the new temporary filename should be able to be
  204. concatenated with.
  205. @return: A pseudorandom, 16 byte string for use in secure filenames.
  206. @rtype: the type of C{path}
  207. """
  208. secureishString = armor(randomBytes(16))[:16]
  209. return _coerceToFilesystemEncoding(path, secureishString)
  210. class AbstractFilePath:
  211. """
  212. Abstract implementation of an L{IFilePath}; must be completed by a
  213. subclass.
  214. This class primarily exists to provide common implementations of certain
  215. methods in L{IFilePath}. It is *not* a required parent class for
  216. L{IFilePath} implementations, just a useful starting point.
  217. """
  218. def getContent(self):
  219. """
  220. Retrieve the contents of the file at this path.
  221. @return: the contents of the file
  222. @rtype: L{bytes}
  223. """
  224. with self.open() as fp:
  225. return fp.read()
  226. def parents(self):
  227. """
  228. Retrieve an iterator of all the ancestors of this path.
  229. @return: an iterator of all the ancestors of this path, from the most
  230. recent (its immediate parent) to the root of its filesystem.
  231. """
  232. path = self
  233. parent = path.parent()
  234. # root.parent() == root, so this means "are we the root"
  235. while path != parent:
  236. yield parent
  237. path = parent
  238. parent = parent.parent()
  239. def children(self):
  240. """
  241. List the children of this path object.
  242. @raise OSError: If an error occurs while listing the directory. If the
  243. error is 'serious', meaning that the operation failed due to an access
  244. violation, exhaustion of some kind of resource (file descriptors or
  245. memory), OSError or a platform-specific variant will be raised.
  246. @raise UnlistableError: If the inability to list the directory is due
  247. to this path not existing or not being a directory, the more specific
  248. OSError subclass L{UnlistableError} is raised instead.
  249. @return: an iterable of all currently-existing children of this object.
  250. """
  251. try:
  252. subnames = self.listdir()
  253. except OSError as ose:
  254. # Under Python 3.3 and higher on Windows, WindowsError is an
  255. # alias for OSError. OSError has a winerror attribute and an
  256. # errno attribute.
  257. #
  258. # The winerror attribute is bound to the Windows error code while
  259. # the errno attribute is bound to a translation of that code to a
  260. # perhaps equivalent POSIX error number.
  261. #
  262. # For further details, refer to:
  263. # https://docs.python.org/3/library/exceptions.html#OSError
  264. if getattr(ose, "winerror", None) in (
  265. ERROR_PATH_NOT_FOUND,
  266. ERROR_FILE_NOT_FOUND,
  267. ERROR_INVALID_NAME,
  268. ERROR_DIRECTORY,
  269. ):
  270. raise UnlistableError(ose)
  271. if ose.errno in (errno.ENOENT, errno.ENOTDIR):
  272. raise UnlistableError(ose)
  273. # Other possible errors here, according to linux manpages:
  274. # EACCES, EMIFLE, ENFILE, ENOMEM. None of these seem like the
  275. # sort of thing which should be handled normally. -glyph
  276. raise
  277. return [self.child(name) for name in subnames]
  278. def walk(self, descend=None):
  279. """
  280. Yield myself, then each of my children, and each of those children's
  281. children in turn.
  282. The optional argument C{descend} is a predicate that takes a FilePath,
  283. and determines whether or not that FilePath is traversed/descended
  284. into. It will be called with each path for which C{isdir} returns
  285. C{True}. If C{descend} is not specified, all directories will be
  286. traversed (including symbolic links which refer to directories).
  287. @param descend: A one-argument callable that will return True for
  288. FilePaths that should be traversed, False otherwise.
  289. @return: a generator yielding FilePath-like objects.
  290. """
  291. yield self
  292. if self.isdir():
  293. for c in self.children():
  294. # we should first see if it's what we want, then we
  295. # can walk through the directory
  296. if descend is None or descend(c):
  297. for subc in c.walk(descend):
  298. if os.path.realpath(self.path).startswith(
  299. os.path.realpath(subc.path)
  300. ):
  301. raise LinkError("Cycle in file graph.")
  302. yield subc
  303. else:
  304. yield c
  305. def sibling(self, path):
  306. """
  307. Return a L{FilePath} with the same directory as this instance but with
  308. a basename of C{path}.
  309. @param path: The basename of the L{FilePath} to return.
  310. @type path: L{str}
  311. @return: The sibling path.
  312. @rtype: L{FilePath}
  313. """
  314. return self.parent().child(path)
  315. def descendant(self, segments):
  316. """
  317. Retrieve a child or child's child of this path.
  318. @param segments: A sequence of path segments as L{str} instances.
  319. @return: A L{FilePath} constructed by looking up the C{segments[0]}
  320. child of this path, the C{segments[1]} child of that path, and so
  321. on.
  322. @since: 10.2
  323. """
  324. path = self
  325. for name in segments:
  326. path = path.child(name)
  327. return path
  328. def segmentsFrom(self, ancestor):
  329. """
  330. Return a list of segments between a child and its ancestor.
  331. For example, in the case of a path X representing /a/b/c/d and a path Y
  332. representing /a/b, C{Y.segmentsFrom(X)} will return C{['c',
  333. 'd']}.
  334. @param ancestor: an instance of the same class as self, ostensibly an
  335. ancestor of self.
  336. @raise ValueError: If the C{ancestor} parameter is not actually an
  337. ancestor, i.e. a path for /x/y/z is passed as an ancestor for /a/b/c/d.
  338. @return: a list of strs
  339. """
  340. # this might be an unnecessarily inefficient implementation but it will
  341. # work on win32 and for zipfiles; later I will deterimine if the
  342. # obvious fast implemenation does the right thing too
  343. f = self
  344. p = f.parent()
  345. segments = []
  346. while f != ancestor and p != f:
  347. segments[0:0] = [f.basename()]
  348. f = p
  349. p = p.parent()
  350. if f == ancestor and segments:
  351. return segments
  352. raise ValueError(f"{ancestor!r} not parent of {self!r}")
  353. # new in 8.0
  354. def __hash__(self):
  355. """
  356. Hash the same as another L{FilePath} with the same path as mine.
  357. """
  358. return hash((self.__class__, self.path))
  359. # pending deprecation in 8.0
  360. def getmtime(self):
  361. """
  362. Deprecated. Use getModificationTime instead.
  363. """
  364. return int(self.getModificationTime())
  365. def getatime(self):
  366. """
  367. Deprecated. Use getAccessTime instead.
  368. """
  369. return int(self.getAccessTime())
  370. def getctime(self):
  371. """
  372. Deprecated. Use getStatusChangeTime instead.
  373. """
  374. return int(self.getStatusChangeTime())
  375. class RWX(FancyEqMixin):
  376. """
  377. A class representing read/write/execute permissions for a single user
  378. category (i.e. user/owner, group, or other/world). Instantiate with
  379. three boolean values: readable? writable? executable?.
  380. @type read: C{bool}
  381. @ivar read: Whether permission to read is given
  382. @type write: C{bool}
  383. @ivar write: Whether permission to write is given
  384. @type execute: C{bool}
  385. @ivar execute: Whether permission to execute is given
  386. @since: 11.1
  387. """
  388. compareAttributes = ("read", "write", "execute")
  389. def __init__(self, readable, writable, executable):
  390. self.read = readable
  391. self.write = writable
  392. self.execute = executable
  393. def __repr__(self) -> str:
  394. return "RWX(read={}, write={}, execute={})".format(
  395. self.read,
  396. self.write,
  397. self.execute,
  398. )
  399. def shorthand(self):
  400. """
  401. Returns a short string representing the permission bits. Looks like
  402. part of what is printed by command line utilities such as 'ls -l'
  403. (e.g. 'rwx')
  404. @return: The shorthand string.
  405. @rtype: L{str}
  406. """
  407. returnval = ["r", "w", "x"]
  408. i = 0
  409. for val in (self.read, self.write, self.execute):
  410. if not val:
  411. returnval[i] = "-"
  412. i += 1
  413. return "".join(returnval)
  414. class Permissions(FancyEqMixin):
  415. """
  416. A class representing read/write/execute permissions. Instantiate with any
  417. portion of the file's mode that includes the permission bits.
  418. @type user: L{RWX}
  419. @ivar user: User/Owner permissions
  420. @type group: L{RWX}
  421. @ivar group: Group permissions
  422. @type other: L{RWX}
  423. @ivar other: Other/World permissions
  424. @since: 11.1
  425. """
  426. compareAttributes = ("user", "group", "other")
  427. def __init__(self, statModeInt):
  428. self.user, self.group, self.other = (
  429. RWX(*(statModeInt & bit > 0 for bit in bitGroup))
  430. for bitGroup in [
  431. [S_IRUSR, S_IWUSR, S_IXUSR],
  432. [S_IRGRP, S_IWGRP, S_IXGRP],
  433. [S_IROTH, S_IWOTH, S_IXOTH],
  434. ]
  435. )
  436. def __repr__(self) -> str:
  437. return f"[{str(self.user)} | {str(self.group)} | {str(self.other)}]"
  438. def shorthand(self):
  439. """
  440. Returns a short string representing the permission bits. Looks like
  441. what is printed by command line utilities such as 'ls -l'
  442. (e.g. 'rwx-wx--x')
  443. @return: The shorthand string.
  444. @rtype: L{str}
  445. """
  446. return "".join([x.shorthand() for x in (self.user, self.group, self.other)])
  447. def _asFilesystemBytes(path: Union[bytes, str], encoding: str = "") -> bytes:
  448. """
  449. Return C{path} as a string of L{bytes} suitable for use on this system's
  450. filesystem.
  451. @param path: The path to be made suitable.
  452. @type path: L{bytes} or L{unicode}
  453. @param encoding: The encoding to use if coercing to L{bytes}. If none is
  454. given, L{sys.getfilesystemencoding} is used.
  455. @return: L{bytes}
  456. """
  457. if isinstance(path, bytes):
  458. return path
  459. else:
  460. if not encoding:
  461. encoding = sys.getfilesystemencoding()
  462. return path.encode(encoding)
  463. def _asFilesystemText(path, encoding=None):
  464. """
  465. Return C{path} as a string of L{unicode} suitable for use on this system's
  466. filesystem.
  467. @param path: The path to be made suitable.
  468. @type path: L{bytes} or L{unicode}
  469. @param encoding: The encoding to use if coercing to L{unicode}. If none
  470. is given, L{sys.getfilesystemencoding} is used.
  471. @return: L{unicode}
  472. """
  473. if type(path) == str:
  474. return path
  475. else:
  476. if encoding is None:
  477. encoding = sys.getfilesystemencoding()
  478. return path.decode(encoding)
  479. def _coerceToFilesystemEncoding(path, newpath, encoding=None):
  480. """
  481. Return a C{newpath} that is suitable for joining to C{path}.
  482. @param path: The path that it should be suitable for joining to.
  483. @param newpath: The new portion of the path to be coerced if needed.
  484. @param encoding: If coerced, the encoding that will be used.
  485. """
  486. if type(path) == bytes:
  487. return _asFilesystemBytes(newpath, encoding=encoding)
  488. else:
  489. return _asFilesystemText(newpath, encoding=encoding)
  490. @comparable
  491. @implementer(IFilePath)
  492. class FilePath(AbstractFilePath):
  493. """
  494. I am a path on the filesystem that only permits 'downwards' access.
  495. Instantiate me with a pathname (for example,
  496. FilePath('/home/myuser/public_html')) and I will attempt to only provide
  497. access to files which reside inside that path. I may be a path to a file,
  498. a directory, or a file which does not exist.
  499. The correct way to use me is to instantiate me, and then do ALL filesystem
  500. access through me. In other words, do not import the 'os' module; if you
  501. need to open a file, call my 'open' method. If you need to list a
  502. directory, call my 'path' method.
  503. Even if you pass me a relative path, I will convert that to an absolute
  504. path internally.
  505. The type of C{path} when instantiating decides the mode of the L{FilePath}.
  506. That is, C{FilePath(b"/")} will return a L{bytes} mode L{FilePath}, and
  507. C{FilePath(u"/")} will return a L{unicode} mode L{FilePath}.
  508. C{FilePath("/")} will return a L{bytes} mode L{FilePath} on Python 2, and a
  509. L{unicode} mode L{FilePath} on Python 3.
  510. Methods that return a new L{FilePath} use the type of the given subpath to
  511. decide its mode. For example, C{FilePath(b"/").child(u"tmp")} will return a
  512. L{unicode} mode L{FilePath}.
  513. @type alwaysCreate: L{bool}
  514. @ivar alwaysCreate: When opening this file, only succeed if the file does
  515. not already exist.
  516. @ivar path: The path from which 'downward' traversal is permitted.
  517. """
  518. _statinfo = None
  519. path: Union[bytes, str] = None # type: ignore[assignment]
  520. def __init__(self, path, alwaysCreate=False):
  521. """
  522. Convert a path string to an absolute path if necessary and initialize
  523. the L{FilePath} with the result.
  524. """
  525. self.path = abspath(path)
  526. self.alwaysCreate = alwaysCreate
  527. def __getstate__(self):
  528. """
  529. Support serialization by discarding cached L{os.stat} results and
  530. returning everything else.
  531. """
  532. d = self.__dict__.copy()
  533. if "_statinfo" in d:
  534. del d["_statinfo"]
  535. return d
  536. @property
  537. def sep(self):
  538. """
  539. Return a filesystem separator.
  540. @return: The native filesystem separator.
  541. @returntype: The same type as C{self.path}.
  542. """
  543. return _coerceToFilesystemEncoding(self.path, os.sep)
  544. def _asBytesPath(self, encoding=None):
  545. """
  546. Return the path of this L{FilePath} as bytes.
  547. @param encoding: The encoding to use if coercing to L{bytes}. If none is
  548. given, L{sys.getfilesystemencoding} is used.
  549. @return: L{bytes}
  550. """
  551. return _asFilesystemBytes(self.path, encoding=encoding)
  552. def _asTextPath(self, encoding=None):
  553. """
  554. Return the path of this L{FilePath} as text.
  555. @param encoding: The encoding to use if coercing to L{unicode}. If none
  556. is given, L{sys.getfilesystemencoding} is used.
  557. @return: L{unicode}
  558. """
  559. return _asFilesystemText(self.path, encoding=encoding)
  560. def asBytesMode(self, encoding=None):
  561. """
  562. Return this L{FilePath} in L{bytes}-mode.
  563. @param encoding: The encoding to use if coercing to L{bytes}. If none is
  564. given, L{sys.getfilesystemencoding} is used.
  565. @return: L{bytes} mode L{FilePath}
  566. """
  567. if type(self.path) == str:
  568. return self.clonePath(self._asBytesPath(encoding=encoding))
  569. return self
  570. def asTextMode(self, encoding=None):
  571. """
  572. Return this L{FilePath} in L{unicode}-mode.
  573. @param encoding: The encoding to use if coercing to L{unicode}. If none
  574. is given, L{sys.getfilesystemencoding} is used.
  575. @return: L{unicode} mode L{FilePath}
  576. """
  577. if type(self.path) == bytes:
  578. return self.clonePath(self._asTextPath(encoding=encoding))
  579. return self
  580. def _getPathAsSameTypeAs(self, pattern):
  581. """
  582. If C{pattern} is C{bytes}, return L{FilePath.path} as L{bytes}.
  583. Otherwise, return L{FilePath.path} as L{unicode}.
  584. @param pattern: The new element of the path that L{FilePath.path} may
  585. need to be coerced to match.
  586. """
  587. if type(pattern) == bytes:
  588. return self._asBytesPath()
  589. else:
  590. return self._asTextPath()
  591. def child(self, path):
  592. """
  593. Create and return a new L{FilePath} representing a path contained by
  594. C{self}.
  595. @param path: The base name of the new L{FilePath}. If this contains
  596. directory separators or parent references it will be rejected.
  597. @type path: L{bytes} or L{unicode}
  598. @raise InsecurePath: If the result of combining this path with C{path}
  599. would result in a path which is not a direct child of this path.
  600. @return: The child path.
  601. @rtype: L{FilePath} with a mode equal to the type of C{path}.
  602. """
  603. colon = _coerceToFilesystemEncoding(path, ":")
  604. sep = _coerceToFilesystemEncoding(path, os.sep)
  605. ourPath = self._getPathAsSameTypeAs(path)
  606. if platform.isWindows() and path.count(colon):
  607. # Catch paths like C:blah that don't have a slash
  608. raise InsecurePath(f"{path!r} contains a colon.")
  609. norm = normpath(path)
  610. if sep in norm:
  611. raise InsecurePath(f"{path!r} contains one or more directory separators")
  612. newpath = abspath(joinpath(ourPath, norm))
  613. if not newpath.startswith(ourPath):
  614. raise InsecurePath(f"{newpath!r} is not a child of {ourPath}")
  615. return self.clonePath(newpath)
  616. def preauthChild(self, path):
  617. """
  618. Use me if C{path} might have slashes in it, but you know they're safe.
  619. @param path: A relative path (ie, a path not starting with C{"/"})
  620. which will be interpreted as a child or descendant of this path.
  621. @type path: L{bytes} or L{unicode}
  622. @return: The child path.
  623. @rtype: L{FilePath} with a mode equal to the type of C{path}.
  624. """
  625. ourPath = self._getPathAsSameTypeAs(path)
  626. newpath = abspath(joinpath(ourPath, normpath(path)))
  627. if not newpath.startswith(ourPath):
  628. raise InsecurePath(f"{newpath} is not a child of {ourPath}")
  629. return self.clonePath(newpath)
  630. def childSearchPreauth(self, *paths):
  631. """
  632. Return my first existing child with a name in C{paths}.
  633. C{paths} is expected to be a list of *pre-secured* path fragments;
  634. in most cases this will be specified by a system administrator and not
  635. an arbitrary user.
  636. If no appropriately-named children exist, this will return L{None}.
  637. @return: L{None} or the child path.
  638. @rtype: L{None} or L{FilePath}
  639. """
  640. for child in paths:
  641. p = self._getPathAsSameTypeAs(child)
  642. jp = joinpath(p, child)
  643. if exists(jp):
  644. return self.clonePath(jp)
  645. def siblingExtensionSearch(self, *exts):
  646. """
  647. Attempt to return a path with my name, given multiple possible
  648. extensions.
  649. Each extension in C{exts} will be tested and the first path which
  650. exists will be returned. If no path exists, L{None} will be returned.
  651. If C{''} is in C{exts}, then if the file referred to by this path
  652. exists, C{self} will be returned.
  653. The extension '*' has a magic meaning, which means "any path that
  654. begins with C{self.path + '.'} is acceptable".
  655. """
  656. for ext in exts:
  657. if not ext and self.exists():
  658. return self
  659. p = self._getPathAsSameTypeAs(ext)
  660. star = _coerceToFilesystemEncoding(ext, "*")
  661. dot = _coerceToFilesystemEncoding(ext, ".")
  662. if ext == star:
  663. basedot = basename(p) + dot
  664. for fn in listdir(dirname(p)):
  665. if fn.startswith(basedot):
  666. return self.clonePath(joinpath(dirname(p), fn))
  667. p2 = p + ext
  668. if exists(p2):
  669. return self.clonePath(p2)
  670. def realpath(self):
  671. """
  672. Returns the absolute target as a L{FilePath} if self is a link, self
  673. otherwise.
  674. The absolute link is the ultimate file or directory the
  675. link refers to (for instance, if the link refers to another link, and
  676. another...). If the filesystem does not support symlinks, or
  677. if the link is cyclical, raises a L{LinkError}.
  678. Behaves like L{os.path.realpath} in that it does not resolve link
  679. names in the middle (ex. /x/y/z, y is a link to w - realpath on z
  680. will return /x/y/z, not /x/w/z).
  681. @return: L{FilePath} of the target path.
  682. @rtype: L{FilePath}
  683. @raises LinkError: if links are not supported or links are cyclical.
  684. """
  685. if self.islink():
  686. result = os.path.realpath(self.path)
  687. if result == self.path:
  688. raise LinkError("Cyclical link - will loop forever")
  689. return self.clonePath(result)
  690. return self
  691. def siblingExtension(self, ext):
  692. """
  693. Attempt to return a path with my name, given the extension at C{ext}.
  694. @param ext: File-extension to search for.
  695. @type ext: L{bytes} or L{unicode}
  696. @return: The sibling path.
  697. @rtype: L{FilePath} with the same mode as the type of C{ext}.
  698. """
  699. ourPath = self._getPathAsSameTypeAs(ext)
  700. return self.clonePath(ourPath + ext)
  701. def linkTo(self, linkFilePath):
  702. """
  703. Creates a symlink to self to at the path in the L{FilePath}
  704. C{linkFilePath}.
  705. Only works on posix systems due to its dependence on
  706. L{os.symlink}. Propagates L{OSError}s up from L{os.symlink} if
  707. C{linkFilePath.parent()} does not exist, or C{linkFilePath} already
  708. exists.
  709. @param linkFilePath: a FilePath representing the link to be created.
  710. @type linkFilePath: L{FilePath}
  711. """
  712. os.symlink(self.path, linkFilePath.path)
  713. def open(self, mode: str = "r") -> IO[bytes]:
  714. """
  715. Open this file using C{mode} or for writing if C{alwaysCreate} is
  716. C{True}.
  717. In all cases the file is opened in binary mode, so it is not necessary
  718. to include C{"b"} in C{mode}.
  719. @param mode: The mode to open the file in. Default is C{"r"}.
  720. @raises AssertionError: If C{"a"} is included in the mode and
  721. C{alwaysCreate} is C{True}.
  722. @return: An open file-like object.
  723. """
  724. if self.alwaysCreate:
  725. assert "a" not in mode, (
  726. "Appending not supported when " "alwaysCreate == True"
  727. )
  728. return self.create()
  729. # Make sure we open with exactly one "b" in the mode.
  730. mode = mode.replace("b", "")
  731. return open(self.path, mode + "b")
  732. # stat methods below
  733. def restat(self, reraise=True):
  734. """
  735. Re-calculate cached effects of 'stat'. To refresh information on this
  736. path after you know the filesystem may have changed, call this method.
  737. @param reraise: a boolean. If true, re-raise exceptions from
  738. L{os.stat}; otherwise, mark this path as not existing, and remove
  739. any cached stat information.
  740. @raise Exception: If C{reraise} is C{True} and an exception occurs
  741. while reloading metadata.
  742. """
  743. try:
  744. self._statinfo = stat(self.path)
  745. except OSError:
  746. self._statinfo = 0
  747. if reraise:
  748. raise
  749. def changed(self):
  750. """
  751. Clear any cached information about the state of this path on disk.
  752. @since: 10.1.0
  753. """
  754. self._statinfo = None
  755. def chmod(self, mode):
  756. """
  757. Changes the permissions on self, if possible. Propagates errors from
  758. L{os.chmod} up.
  759. @param mode: integer representing the new permissions desired (same as
  760. the command line chmod)
  761. @type mode: L{int}
  762. """
  763. os.chmod(self.path, mode)
  764. def getsize(self):
  765. """
  766. Retrieve the size of this file in bytes.
  767. @return: The size of the file at this file path in bytes.
  768. @raise Exception: if the size cannot be obtained.
  769. @rtype: L{int}
  770. """
  771. st = self._statinfo
  772. if not st:
  773. self.restat()
  774. st = self._statinfo
  775. return st.st_size
  776. def getModificationTime(self):
  777. """
  778. Retrieve the time of last access from this file.
  779. @return: a number of seconds from the epoch.
  780. @rtype: L{float}
  781. """
  782. st = self._statinfo
  783. if not st:
  784. self.restat()
  785. st = self._statinfo
  786. return float(st.st_mtime)
  787. def getStatusChangeTime(self):
  788. """
  789. Retrieve the time of the last status change for this file.
  790. @return: a number of seconds from the epoch.
  791. @rtype: L{float}
  792. """
  793. st = self._statinfo
  794. if not st:
  795. self.restat()
  796. st = self._statinfo
  797. return float(st.st_ctime)
  798. def getAccessTime(self):
  799. """
  800. Retrieve the time that this file was last accessed.
  801. @return: a number of seconds from the epoch.
  802. @rtype: L{float}
  803. """
  804. st = self._statinfo
  805. if not st:
  806. self.restat()
  807. st = self._statinfo
  808. return float(st.st_atime)
  809. def getInodeNumber(self):
  810. """
  811. Retrieve the file serial number, also called inode number, which
  812. distinguishes this file from all other files on the same device.
  813. @raise NotImplementedError: if the platform is Windows, since the
  814. inode number would be a dummy value for all files in Windows
  815. @return: a number representing the file serial number
  816. @rtype: L{int}
  817. @since: 11.0
  818. """
  819. if platform.isWindows():
  820. raise NotImplementedError
  821. st = self._statinfo
  822. if not st:
  823. self.restat()
  824. st = self._statinfo
  825. return st.st_ino
  826. def getDevice(self):
  827. """
  828. Retrieves the device containing the file. The inode number and device
  829. number together uniquely identify the file, but the device number is
  830. not necessarily consistent across reboots or system crashes.
  831. @raise NotImplementedError: if the platform is Windows, since the
  832. device number would be 0 for all partitions on a Windows platform
  833. @return: a number representing the device
  834. @rtype: L{int}
  835. @since: 11.0
  836. """
  837. if platform.isWindows():
  838. raise NotImplementedError
  839. st = self._statinfo
  840. if not st:
  841. self.restat()
  842. st = self._statinfo
  843. return st.st_dev
  844. def getNumberOfHardLinks(self):
  845. """
  846. Retrieves the number of hard links to the file.
  847. This count keeps track of how many directories have entries for this
  848. file. If the count is ever decremented to zero then the file itself is
  849. discarded as soon as no process still holds it open. Symbolic links
  850. are not counted in the total.
  851. @raise NotImplementedError: if the platform is Windows, since Windows
  852. doesn't maintain a link count for directories, and L{os.stat} does
  853. not set C{st_nlink} on Windows anyway.
  854. @return: the number of hard links to the file
  855. @rtype: L{int}
  856. @since: 11.0
  857. """
  858. if platform.isWindows():
  859. raise NotImplementedError
  860. st = self._statinfo
  861. if not st:
  862. self.restat()
  863. st = self._statinfo
  864. return st.st_nlink
  865. def getUserID(self):
  866. """
  867. Returns the user ID of the file's owner.
  868. @raise NotImplementedError: if the platform is Windows, since the UID
  869. is always 0 on Windows
  870. @return: the user ID of the file's owner
  871. @rtype: L{int}
  872. @since: 11.0
  873. """
  874. if platform.isWindows():
  875. raise NotImplementedError
  876. st = self._statinfo
  877. if not st:
  878. self.restat()
  879. st = self._statinfo
  880. return st.st_uid
  881. def getGroupID(self):
  882. """
  883. Returns the group ID of the file.
  884. @raise NotImplementedError: if the platform is Windows, since the GID
  885. is always 0 on windows
  886. @return: the group ID of the file
  887. @rtype: L{int}
  888. @since: 11.0
  889. """
  890. if platform.isWindows():
  891. raise NotImplementedError
  892. st = self._statinfo
  893. if not st:
  894. self.restat()
  895. st = self._statinfo
  896. return st.st_gid
  897. def getPermissions(self):
  898. """
  899. Returns the permissions of the file. Should also work on Windows,
  900. however, those permissions may not be what is expected in Windows.
  901. @return: the permissions for the file
  902. @rtype: L{Permissions}
  903. @since: 11.1
  904. """
  905. st = self._statinfo
  906. if not st:
  907. self.restat()
  908. st = self._statinfo
  909. return Permissions(S_IMODE(st.st_mode))
  910. def exists(self):
  911. """
  912. Check if this L{FilePath} exists.
  913. @return: C{True} if the stats of C{path} can be retrieved successfully,
  914. C{False} in the other cases.
  915. @rtype: L{bool}
  916. """
  917. if self._statinfo:
  918. return True
  919. else:
  920. self.restat(False)
  921. if self._statinfo:
  922. return True
  923. else:
  924. return False
  925. def isdir(self):
  926. """
  927. Check if this L{FilePath} refers to a directory.
  928. @return: C{True} if this L{FilePath} refers to a directory, C{False}
  929. otherwise.
  930. @rtype: L{bool}
  931. """
  932. st = self._statinfo
  933. if not st:
  934. self.restat(False)
  935. st = self._statinfo
  936. if not st:
  937. return False
  938. return S_ISDIR(st.st_mode)
  939. def isfile(self):
  940. """
  941. Check if this file path refers to a regular file.
  942. @return: C{True} if this L{FilePath} points to a regular file (not a
  943. directory, socket, named pipe, etc), C{False} otherwise.
  944. @rtype: L{bool}
  945. """
  946. st = self._statinfo
  947. if not st:
  948. self.restat(False)
  949. st = self._statinfo
  950. if not st:
  951. return False
  952. return S_ISREG(st.st_mode)
  953. def isBlockDevice(self):
  954. """
  955. Returns whether the underlying path is a block device.
  956. @return: C{True} if it is a block device, C{False} otherwise
  957. @rtype: L{bool}
  958. @since: 11.1
  959. """
  960. st = self._statinfo
  961. if not st:
  962. self.restat(False)
  963. st = self._statinfo
  964. if not st:
  965. return False
  966. return S_ISBLK(st.st_mode)
  967. def isSocket(self):
  968. """
  969. Returns whether the underlying path is a socket.
  970. @return: C{True} if it is a socket, C{False} otherwise
  971. @rtype: L{bool}
  972. @since: 11.1
  973. """
  974. st = self._statinfo
  975. if not st:
  976. self.restat(False)
  977. st = self._statinfo
  978. if not st:
  979. return False
  980. return S_ISSOCK(st.st_mode)
  981. def islink(self):
  982. """
  983. Check if this L{FilePath} points to a symbolic link.
  984. @return: C{True} if this L{FilePath} points to a symbolic link,
  985. C{False} otherwise.
  986. @rtype: L{bool}
  987. """
  988. # We can't use cached stat results here, because that is the stat of
  989. # the destination - (see #1773) which in *every case* but this one is
  990. # the right thing to use. We could call lstat here and use that, but
  991. # it seems unlikely we'd actually save any work that way. -glyph
  992. return islink(self.path)
  993. def isabs(self):
  994. """
  995. Check if this L{FilePath} refers to an absolute path.
  996. This always returns C{True}.
  997. @return: C{True}, always.
  998. @rtype: L{bool}
  999. """
  1000. return isabs(self.path)
  1001. def listdir(self):
  1002. """
  1003. List the base names of the direct children of this L{FilePath}.
  1004. @return: A L{list} of L{bytes}/L{unicode} giving the names of the
  1005. contents of the directory this L{FilePath} refers to. These names
  1006. are relative to this L{FilePath}.
  1007. @rtype: L{list}
  1008. @raise OSError: Any exception the platform L{os.listdir} implementation
  1009. may raise.
  1010. """
  1011. return listdir(self.path)
  1012. def splitext(self):
  1013. """
  1014. Split the file path into a pair C{(root, ext)} such that
  1015. C{root + ext == path}.
  1016. @return: Tuple where the first item is the filename and second item is
  1017. the file extension. See Python docs for L{os.path.splitext}.
  1018. @rtype: L{tuple}
  1019. """
  1020. return splitext(self.path)
  1021. def __repr__(self) -> str:
  1022. return f"FilePath({self.path!r})"
  1023. def touch(self):
  1024. """
  1025. Updates the access and last modification times of the file at this
  1026. file path to the current time. Also creates the file if it does not
  1027. already exist.
  1028. @raise Exception: if unable to create or modify the last modification
  1029. time of the file.
  1030. """
  1031. try:
  1032. self.open("a").close()
  1033. except OSError:
  1034. pass
  1035. utime(self.path, None)
  1036. def remove(self):
  1037. """
  1038. Removes the file or directory that is represented by self. If
  1039. C{self.path} is a directory, recursively remove all its children
  1040. before removing the directory. If it's a file or link, just delete it.
  1041. """
  1042. if self.isdir() and not self.islink():
  1043. for child in self.children():
  1044. child.remove()
  1045. os.rmdir(self.path)
  1046. else:
  1047. os.remove(self.path)
  1048. self.changed()
  1049. def makedirs(self, ignoreExistingDirectory=False):
  1050. """
  1051. Create all directories not yet existing in C{path} segments, using
  1052. L{os.makedirs}.
  1053. @param ignoreExistingDirectory: Don't raise L{OSError} if directory
  1054. already exists.
  1055. @type ignoreExistingDirectory: L{bool}
  1056. @return: L{None}
  1057. """
  1058. try:
  1059. return os.makedirs(self.path)
  1060. except OSError as e:
  1061. if not (
  1062. e.errno == errno.EEXIST and ignoreExistingDirectory and self.isdir()
  1063. ):
  1064. raise
  1065. def globChildren(self, pattern):
  1066. """
  1067. Assuming I am representing a directory, return a list of FilePaths
  1068. representing my children that match the given pattern.
  1069. @param pattern: A glob pattern to use to match child paths.
  1070. @type pattern: L{unicode} or L{bytes}
  1071. @return: A L{list} of matching children.
  1072. @rtype: L{list} of L{FilePath}, with the mode of C{pattern}'s type
  1073. """
  1074. sep = _coerceToFilesystemEncoding(pattern, os.sep)
  1075. ourPath = self._getPathAsSameTypeAs(pattern)
  1076. import glob
  1077. path = ourPath[-1] == sep and ourPath + pattern or sep.join([ourPath, pattern])
  1078. return [self.clonePath(p) for p in glob.glob(path)]
  1079. def basename(self):
  1080. """
  1081. Retrieve the final component of the file path's path (everything
  1082. after the final path separator).
  1083. @return: The final component of the L{FilePath}'s path (Everything
  1084. after the final path separator).
  1085. @rtype: the same type as this L{FilePath}'s C{path} attribute
  1086. """
  1087. return basename(self.path)
  1088. def dirname(self):
  1089. """
  1090. Retrieve all of the components of the L{FilePath}'s path except the
  1091. last one (everything up to the final path separator).
  1092. @return: All of the components of the L{FilePath}'s path except the
  1093. last one (everything up to the final path separator).
  1094. @rtype: the same type as this L{FilePath}'s C{path} attribute
  1095. """
  1096. return dirname(self.path)
  1097. def parent(self):
  1098. """
  1099. A file path for the directory containing the file at this file path.
  1100. @return: A L{FilePath} representing the path which directly contains
  1101. this L{FilePath}.
  1102. @rtype: L{FilePath}
  1103. """
  1104. return self.clonePath(self.dirname())
  1105. def setContent(self, content, ext=b".new"):
  1106. """
  1107. Replace the file at this path with a new file that contains the given
  1108. bytes, trying to avoid data-loss in the meanwhile.
  1109. On UNIX-like platforms, this method does its best to ensure that by the
  1110. time this method returns, either the old contents I{or} the new
  1111. contents of the file will be present at this path for subsequent
  1112. readers regardless of premature device removal, program crash, or power
  1113. loss, making the following assumptions:
  1114. - your filesystem is journaled (i.e. your filesystem will not
  1115. I{itself} lose data due to power loss)
  1116. - your filesystem's C{rename()} is atomic
  1117. - your filesystem will not discard new data while preserving new
  1118. metadata (see U{http://mjg59.livejournal.com/108257.html} for
  1119. more detail)
  1120. On most versions of Windows there is no atomic C{rename()} (see
  1121. U{http://bit.ly/win32-overwrite} for more information), so this method
  1122. is slightly less helpful. There is a small window where the file at
  1123. this path may be deleted before the new file is moved to replace it:
  1124. however, the new file will be fully written and flushed beforehand so
  1125. in the unlikely event that there is a crash at that point, it should be
  1126. possible for the user to manually recover the new version of their
  1127. data. In the future, Twisted will support atomic file moves on those
  1128. versions of Windows which I{do} support them: see U{Twisted ticket
  1129. 3004<http://twistedmatrix.com/trac/ticket/3004>}.
  1130. This method should be safe for use by multiple concurrent processes,
  1131. but note that it is not easy to predict which process's contents will
  1132. ultimately end up on disk if they invoke this method at close to the
  1133. same time.
  1134. @param content: The desired contents of the file at this path.
  1135. @type content: L{bytes}
  1136. @param ext: An extension to append to the temporary filename used to
  1137. store the bytes while they are being written. This can be used to
  1138. make sure that temporary files can be identified by their suffix,
  1139. for cleanup in case of crashes.
  1140. @type ext: L{bytes}
  1141. """
  1142. sib = self.temporarySibling(ext)
  1143. with sib.open("w") as f:
  1144. f.write(content)
  1145. if platform.isWindows() and exists(self.path):
  1146. os.unlink(self.path)
  1147. os.rename(sib.path, self.asBytesMode().path)
  1148. def __cmp__(self, other):
  1149. if not isinstance(other, FilePath):
  1150. return NotImplemented
  1151. return cmp(self.path, other.path)
  1152. def createDirectory(self):
  1153. """
  1154. Create the directory the L{FilePath} refers to.
  1155. @see: L{makedirs}
  1156. @raise OSError: If the directory cannot be created.
  1157. """
  1158. os.mkdir(self.path)
  1159. def requireCreate(self, val=1):
  1160. """
  1161. Sets the C{alwaysCreate} variable.
  1162. @param val: C{True} or C{False}, indicating whether opening this path
  1163. will be required to create the file or not.
  1164. @type val: L{bool}
  1165. @return: L{None}
  1166. """
  1167. self.alwaysCreate = val
  1168. def create(self) -> IO[bytes]:
  1169. """
  1170. Exclusively create a file, only if this file previously did not exist.
  1171. @return: A file-like object opened from this path.
  1172. """
  1173. fdint = os.open(self.path, _CREATE_FLAGS)
  1174. # XXX TODO: 'name' attribute of returned files is not mutable or
  1175. # settable via fdopen, so this file is slightly less functional than the
  1176. # one returned from 'open' by default. send a patch to Python...
  1177. return cast(IO[bytes], os.fdopen(fdint, "w+b"))
  1178. def temporarySibling(self, extension=b""):
  1179. """
  1180. Construct a path referring to a sibling of this path.
  1181. The resulting path will be unpredictable, so that other subprocesses
  1182. should neither accidentally attempt to refer to the same path before it
  1183. is created, nor they should other processes be able to guess its name
  1184. in advance.
  1185. @param extension: A suffix to append to the created filename. (Note
  1186. that if you want an extension with a '.' you must include the '.'
  1187. yourself.)
  1188. @type extension: L{bytes} or L{unicode}
  1189. @return: a path object with the given extension suffix, C{alwaysCreate}
  1190. set to True.
  1191. @rtype: L{FilePath} with a mode equal to the type of C{extension}
  1192. """
  1193. ourPath = self._getPathAsSameTypeAs(extension)
  1194. sib = self.sibling(
  1195. _secureEnoughString(ourPath)
  1196. + self.clonePath(ourPath).basename()
  1197. + extension
  1198. )
  1199. sib.requireCreate()
  1200. return sib
  1201. _chunkSize = 2 ** 2 ** 2 ** 2
  1202. def copyTo(self, destination, followLinks=True):
  1203. """
  1204. Copies self to destination.
  1205. If self doesn't exist, an OSError is raised.
  1206. If self is a directory, this method copies its children (but not
  1207. itself) recursively to destination - if destination does not exist as a
  1208. directory, this method creates it. If destination is a file, an
  1209. IOError will be raised.
  1210. If self is a file, this method copies it to destination. If
  1211. destination is a file, this method overwrites it. If destination is a
  1212. directory, an IOError will be raised.
  1213. If self is a link (and followLinks is False), self will be copied
  1214. over as a new symlink with the same target as returned by os.readlink.
  1215. That means that if it is absolute, both the old and new symlink will
  1216. link to the same thing. If it's relative, then perhaps not (and
  1217. it's also possible that this relative link will be broken).
  1218. File/directory permissions and ownership will NOT be copied over.
  1219. If followLinks is True, symlinks are followed so that they're treated
  1220. as their targets. In other words, if self is a link, the link's target
  1221. will be copied. If destination is a link, self will be copied to the
  1222. destination's target (the actual destination will be destination's
  1223. target). Symlinks under self (if self is a directory) will be
  1224. followed and its target's children be copied recursively.
  1225. If followLinks is False, symlinks will be copied over as symlinks.
  1226. @param destination: the destination (a FilePath) to which self
  1227. should be copied
  1228. @param followLinks: whether symlinks in self should be treated as links
  1229. or as their targets
  1230. """
  1231. if self.islink() and not followLinks:
  1232. os.symlink(os.readlink(self.path), destination.path)
  1233. return
  1234. # XXX TODO: *thorough* audit and documentation of the exact desired
  1235. # semantics of this code. Right now the behavior of existent
  1236. # destination symlinks is convenient, and quite possibly correct, but
  1237. # its security properties need to be explained.
  1238. if self.isdir():
  1239. if not destination.exists():
  1240. destination.createDirectory()
  1241. for child in self.children():
  1242. destChild = destination.child(child.basename())
  1243. child.copyTo(destChild, followLinks)
  1244. elif self.isfile():
  1245. with destination.open("w") as writefile, self.open() as readfile:
  1246. while 1:
  1247. # XXX TODO: optionally use os.open, os.read and
  1248. # O_DIRECT and use os.fstatvfs to determine chunk sizes
  1249. # and make *****sure**** copy is page-atomic; the
  1250. # following is good enough for 99.9% of everybody and
  1251. # won't take a week to audit though.
  1252. chunk = readfile.read(self._chunkSize)
  1253. writefile.write(chunk)
  1254. if len(chunk) < self._chunkSize:
  1255. break
  1256. elif not self.exists():
  1257. raise OSError(errno.ENOENT, "No such file or directory")
  1258. else:
  1259. # If you see the following message because you want to copy
  1260. # symlinks, fifos, block devices, character devices, or unix
  1261. # sockets, please feel free to add support to do sensible things in
  1262. # reaction to those types!
  1263. raise NotImplementedError("Only copying of files and directories supported")
  1264. def moveTo(self, destination, followLinks=True):
  1265. """
  1266. Move self to destination - basically renaming self to whatever
  1267. destination is named.
  1268. If destination is an already-existing directory,
  1269. moves all children to destination if destination is empty. If
  1270. destination is a non-empty directory, or destination is a file, an
  1271. OSError will be raised.
  1272. If moving between filesystems, self needs to be copied, and everything
  1273. that applies to copyTo applies to moveTo.
  1274. @param destination: the destination (a FilePath) to which self
  1275. should be copied
  1276. @param followLinks: whether symlinks in self should be treated as links
  1277. or as their targets (only applicable when moving between
  1278. filesystems)
  1279. """
  1280. try:
  1281. os.rename(self._getPathAsSameTypeAs(destination.path), destination.path)
  1282. except OSError as ose:
  1283. if ose.errno == errno.EXDEV:
  1284. # man 2 rename, ubuntu linux 5.10 "breezy":
  1285. # oldpath and newpath are not on the same mounted filesystem.
  1286. # (Linux permits a filesystem to be mounted at multiple
  1287. # points, but rename(2) does not work across different mount
  1288. # points, even if the same filesystem is mounted on both.)
  1289. # that means it's time to copy trees of directories!
  1290. secsib = destination.temporarySibling()
  1291. self.copyTo(secsib, followLinks) # slow
  1292. secsib.moveTo(destination, followLinks) # visible
  1293. # done creating new stuff. let's clean me up.
  1294. mysecsib = self.temporarySibling()
  1295. self.moveTo(mysecsib, followLinks) # visible
  1296. mysecsib.remove() # slow
  1297. else:
  1298. raise
  1299. else:
  1300. self.changed()
  1301. destination.changed()
  1302. FilePath.clonePath = FilePath # type: ignore[attr-defined]