Ticket #5027: filepath-api-docs.2.patch

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

Fixed issues with the new documentation.

  • twisted/python/filepath.py

     
    246246
    247247
    248248    def sibling(self, path):
     249        """
     250        Return a L{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        """
     387        Initialize the L{FilePath}
     388        """
     389
    382390        self.path = abspath(path)
    383391        self.alwaysCreate = alwaysCreate
    384392
    385393    def __getstate__(self):
     394        """
     395        Internal method for pickling
     396        """
     397
    386398        d = self.__dict__.copy()
    387399        if d.has_key('statinfo'):
    388400            del d['statinfo']
    389401        return d
    390402
    391403    def child(self, path):
     404        """
     405        Returns a new L{FilePath} to the L{FilePath}'s child.
     406
     407        @param path: The path to test for child-ness
     408        @type path: String
     409        @raise InsecurePath: If path is not a child of the L{FilePath}
     410        """
     411       
    392412        if platform.isWindows() and path.count(":"):
    393413            # Catch paths like C:blah that don't have a slash
    394414            raise InsecurePath("%r contains a colon." % (path,))
     
    719739
    720740    def exists(self):
    721741        """
    722         Check if the C{path} exists.
     742        Check if the L{FilePath} exists.
    723743
    724744        @return: C{True} if the stats of C{path} can be retrieved successfully,
    725745            C{False} in the other cases.
     
    736756
    737757
    738758    def isdir(self):
     759        """
     760        @return: C{True} if the L{FilePath} points to a directory.
     761        """
    739762        st = self.statinfo
    740763        if not st:
    741764            self.restat(False)
     
    745768        return S_ISDIR(st.st_mode)
    746769
    747770    def isfile(self):
     771        """
     772        @return: C{True} if the L{FilePath} points to a file.
     773        """
     774
    748775        st = self.statinfo
    749776        if not st:
    750777            self.restat(False)
     
    754781        return S_ISREG(st.st_mode)
    755782
    756783    def islink(self):
     784        """
     785        @return: C{True} if the L{FilePath} points to a link.
     786        """
    757787        # We can't use cached stat results here, because that is the stat of
    758788        # the destination - (see #1773) which in *every case* but this one is
    759789        # the right thing to use.  We could call lstat here and use that, but
     
    761791        return islink(self.path)
    762792
    763793    def isabs(self):
     794        """
     795        @return C{True} if the L{FilePath} is absolute
     796        """
    764797        return isabs(self.path)
    765798
    766799    def listdir(self):
     800        """
     801        @return: List of the L{FilePath}'s children
     802        @raise: OSError if C{self.isfile()} is True.
     803        """
    767804        return listdir(self.path)
    768805
    769806    def splitext(self):
     807        """
     808        @return: tuple where the first item is the filename and second
     809        item is the file extension. See Python docs for C{os.path.splitext}
     810        """
    770811        return splitext(self.path)
    771812
    772813    def __repr__(self):
    773814        return 'FilePath(%r)' % (self.path,)
    774815
    775816    def touch(self):
     817        """
     818        Update the access and modified times of the L{FilePath}'s file.
     819        Fails silently.
     820        """
    776821        try:
    777822            self.open('a').close()
    778823        except IOError:
     
    814859        return map(self.clonePath, glob.glob(path))
    815860
    816861    def basename(self):
     862        """
     863        @return: The final component of the L{FilePath}'s path
     864        (Everything after the final path seperator)
     865        """
    817866        return basename(self.path)
    818867
    819868    def dirname(self):
     869        """
     870        @return: The name of the L{FilePath}'s parent directory
     871        """
    820872        return dirname(self.path)
    821873
    822874    def parent(self):
     875        """
     876        @return: A L{FilePath} representing this L{FilePath}'s parent
     877        """
    823878        return self.clonePath(self.dirname())
    824879
    825880
     
    889944        return cmp(self.path, other.path)
    890945
    891946    def createDirectory(self):
     947        """
     948        Creates the directory the L{FilePath} points to if it doesn't exist
     949        You may want to use makedirs instead.
     950        """
    892951        os.mkdir(self.path)
    893952
    894953    def requireCreate(self, val=1):
    895954        self.alwaysCreate = val
    896955
    897956    def create(self):
    898         """Exclusively create a file, only if this file previously did not exist.
    899957        """
     958        Exclusively create a file, only if this file previously did not exist.
     959        """
    900960        fdint = os.open(self.path, _CREATE_FLAGS)
    901961
    902962        # XXX TODO: 'name' attribute of returned files is not mutable or