Ticket #5027: filepath-api-docs.patch

File filepath-api-docs.patch, 4.2 KB (added by Corey Richardson, 7 years ago)

Diff of my changes.

  • twisted/python/filepath.py

     
    246246
    247247
    248248    def sibling(self, path):
     249        """
     250        Return a C{FilePath} that is the sibbling of the current,
     251        named C{path}.
     252        """
    249253        return self.parent().child(path)
    250254
    251255
     
    336340    Instantiate me with a pathname (for example,
    337341    FilePath('/home/myuser/public_html')) and I will attempt to only provide
    338342    access to files which reside inside that path.  I may be a path to a file,
    339     a directory, or a file which does not exist.
     343    a directory, or a file which does not exist. Unicode pathnames work.
    340344
    341345    The correct way to use me is to instantiate me, and then do ALL filesystem
    342346    access through me.  In other words, do not import the 'os' module; if you
     
    379383    path = None
    380384
    381385    def __init__(self, path, alwaysCreate=False):
     386        """Initialize the C{FilePath}"""
     387
    382388        self.path = abspath(path)
    383389        self.alwaysCreate = alwaysCreate
    384390
    385391    def __getstate__(self):
     392        """Internal method for pickling"""
     393
    386394        d = self.__dict__.copy()
    387395        if d.has_key('statinfo'):
    388396            del d['statinfo']
    389397        return d
    390398
    391399    def child(self, path):
     400        """Returns a new C{FilePath} to the C{FilePath}'s child.
     401
     402        @param path: The path to test for child-ness
     403        @type path: String
     404        @raise InsecurePath: If path is not a child of the C{FilePath}
     405        """
     406       
    392407        if platform.isWindows() and path.count(":"):
    393408            # Catch paths like C:blah that don't have a slash
    394409            raise InsecurePath("%r contains a colon." % (path,))
     
    719734
    720735    def exists(self):
    721736        """
    722         Check if the C{path} exists.
     737        Check if the C{FilePath} exists.
    723738
    724739        @return: C{True} if the stats of C{path} can be retrieved successfully,
    725740            C{False} in the other cases.
     
    736751
    737752
    738753    def isdir(self):
     754        """@return: C{True} if the C{FilePath} points to a directory"""
    739755        st = self.statinfo
    740756        if not st:
    741757            self.restat(False)
     
    745761        return S_ISDIR(st.st_mode)
    746762
    747763    def isfile(self):
     764        """@return: C{True} if the C{FilePath} points to a file"""
     765
    748766        st = self.statinfo
    749767        if not st:
    750768            self.restat(False)
     
    754772        return S_ISREG(st.st_mode)
    755773
    756774    def islink(self):
     775        """@return: C{True} if the C{FilePath} points to a link"""
    757776        # We can't use cached stat results here, because that is the stat of
    758777        # the destination - (see #1773) which in *every case* but this one is
    759778        # the right thing to use.  We could call lstat here and use that, but
     
    761780        return islink(self.path)
    762781
    763782    def isabs(self):
     783        """@return C{True} if the C{FilePath} is absolute"""
    764784        return isabs(self.path)
    765785
    766786    def listdir(self):
     787        """
     788        @return: List of the C{FilePath}'s children
     789        @raise: OSError if C{self.isfile()} is True.
     790        """
    767791        return listdir(self.path)
    768792
    769793    def splitext(self):
     794        """@return: tuple where the first item is the filename and second
     795        item is the file extension. See Python docs for C{os.path.splitext}"""
    770796        return splitext(self.path)
    771797
    772798    def __repr__(self):
    773799        return 'FilePath(%r)' % (self.path,)
    774800
    775801    def touch(self):
     802        """Update the access and modified times of the C{FilePath}'s file."""
    776803        try:
    777804            self.open('a').close()
    778805        except IOError:
     
    814841        return map(self.clonePath, glob.glob(path))
    815842
    816843    def basename(self):
     844        """@return: The final component of the C{FilePath}'s path"""
    817845        return basename(self.path)
    818846
    819847    def dirname(self):
     848        """@return: The name of the C{FilePath}'s parent directory"""
    820849        return dirname(self.path)
    821850
    822851    def parent(self):
     852        """@return: A C{FilePath} representing this C{FilePath}'s parent"""
    823853        return self.clonePath(self.dirname())
    824854
    825855
     
    889919        return cmp(self.path, other.path)
    890920
    891921    def createDirectory(self):
     922        """Creates a child directory in the C{FilePath}"""
    892923        os.mkdir(self.path)
    893924
    894925    def requireCreate(self, val=1):