Package core :: Module file_system |
[hide private]
[frames] | no frames]

# Source Code for Module core.file_system

      1  # Copyright 2011 the original author or authors.
      2  #
      3  # Licensed under the Apache License, Version 2.0 (the "License");
      4  # you may not use this file except in compliance with the License.
      5  # You may obtain a copy of the License at
      6  #
      7  #      http://www.apache.org/licenses/LICENSE-2.0
      8  #
      9  # Unless required by applicable law or agreed to in writing, software
     10  # distributed under the License is distributed on an "AS IS" BASIS,
     11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     12  # See the License for the specific language governing permissions and
     13  # limitations under the License.
     14
     15  import datetime
     16  import core.streams
     17  import org.vertx.java.core
     18  import org.vertx.java.deploy.impl.VertxLocator
     19
     20  from core.buffer import Buffer
     21
     22  __author__ = "Scott Horn"
     23  __email__ = "scott@hornmicro.com"
     24  __credits__ = "Based entirely on work by Tim Fox http://tfox.org"
     25
     26 -class FileProps(object):
     27      """Represents the properties of a file on the file system"""
     28
     29 -    def __init__(self, java_obj):
     30          self.java_obj = java_obj
     31
     32      @property
     33 -    def creation_time(self):
     34          """return [Time] The creation time of the file."""
     35          return datetime.datetime.fromtimestamp(self.java_obj.creationTime.getTime() / 1000)
     36
     37      @property
     38 -    def last_access_time(self):
     39          """return [Time] The last access time of the file."""
     40          return datetime.datetime.fromtimestamp(self.java_obj.lastAccessTime.getTime() / 1000)
     41
     42      @property
     43 -    def last_modified_time(self):
     44          """return The last modified time of the file."""
     45          return datetime.datetime.fromtimestamp(self.java_obj.lastModifiedTime.getTime() / 1000)
     46
     47      @property
     48 -    def directory(self):
     49          """return is the file a directory"""
     50          return self.java_obj.isDirectory
     51
     52      @property
     53 -    def other(self):
     54          """return Is the file some other file type?"""
     55          return self.java_obj.isOther
     56
     57      @property
     58 -    def regular_file(self):
     59          """returns   Is it a regular file?"""
     60          return self.java_obj.isRegularFile
     61
     62      @property
     63 -    def symbolic_link(self):
     64          """returns is it a symbolic link?"""
     65          return self.java_obj.isSymbolicLink
     66
     67      @property
     68 -    def size(self):
     69          """returnsthe size of the file, in bytes."""
     70          return self.java_obj.size
     71
     72 -class FSProps(object):
     73      """Represents the properties of a file system"""
     74
     75 -    def __init__(self, java_obj):
     76          self.java_obj = java_obj
     77
     78      @property
     79 -    def total_space(self):
     80          """returns  the total space on the file system, in bytes."""
     81          return self.java_obj.totalSpace()
     82
     83      @property
     84 -    def unallocated_space(self):
     85          """returns unallocated space on the file system, in bytes."""
     86          return self.java_obj.unallocatedSpace()
     87
     88      @property
     89 -    def usable_space(self):
     90          """returns usable space on the file system, in bytes."""
     91          return self.java_obj.usableSpace()
     92
     93 -class AsyncFile(object):
     94      """Represents a file on the file-system which can be read from, or written to asynchronously.
     95      Methods also exist to get a read stream or a write stream on the file. This allows the data to be pumped to and from
     96      other streams, e.g. an HttpClientRequest instance, using the Pump class
     97      """
     98 -    def __init__(self, java_obj):
     99          self.java_obj = java_obj
    100
    101 -    def close(self, handler):
    102          """Close the file, asynchronously."""
    103          self.java_obj.close(FSWrappedHandler(handler))
    104
    105
    106 -    def write(self, buffer, position, handler):
    107          """Write a Buffer to the file, asynchronously.
    108          When multiple writes are invoked on the same file
    109          there are no guarantees as to order in which those writes actually occur.
    110
    111          Keyword arguments:
    112          @param buffer: the buffer to write
    113          @param position: the position in the file where to write the buffer. Position is measured in bytes and
    114          starts with zero at the beginning of the file.
    115          """
    116          self.java_obj.write(buffer._to_java_buffer(), position, FSWrappedHandler(handler))
    117
    118 -    def read(self, buffer, offset, position, length, handler):
    119          """Reads some data from a file into a buffer, asynchronously.
    120          When multiple reads are invoked on the same file
    121          there are no guarantees as to order in which those reads actually occur.
    122
    123          Keyword arguments
    124          @param buffer: the buffer into which the data which is read is written.
    125          @param offset: the position in the buffer where to start writing the data.
    126          @param position: the position in the file where to read the data.
    127          @param length: the number of bytes to read.
    128          """
    129          def converter(buffer):
    130              return Buffer(buffer)
    131          self.java_obj.read(buffer._to_java_buffer(), offset, position, length, FSWrappedHandler(handler, converter))
    132
    133      @property
    134 -    def write_stream(self):
    135          """returns a write stream operating on the file."""
    136          return AsyncFileWriteStream(self.java_obj.getWriteStream())
    137
    138      @property
    139 -    def read_stream(self):
    140          """returns  [ReadStream] A read stream operating on the file."""
    141          return AsyncFileReadStream(self.java_obj.getReadStream())
    142
    143 -    def flush(self):
    144          """Flush any writes made to this file to underlying persistent storage, asynchronously.
    145          If the file was opened with flush set to true then calling this method will have no effect.
    146          Keyword arguments:
    147
    148          @param handler: the handler which is called on completion.
    149          """
    150          Future(self.java_obj.flush())
    151
    152 -class AsyncFileWriteStream(core.streams.WriteStream):
    153 -    def __init__(self, java_obj):
    154          self.java_obj = java_obj
    155
    156 -class AsyncFileReadStream(core.streams.ReadStream):
    157 -    def __init__(self, java_obj):
    158          self.java_obj = java_obj
    159
    160 -class FSWrappedHandler(org.vertx.java.core.AsyncResultHandler):
    161 -    def __init__(self, handler, result_converter=None):
    162          self.handler = handler
    163          self.result_converter = result_converter
    164
    165 -    def handle(self, async_result):
    166          if not (self.handler is None):
    167              if async_result.exception is None:
    168                  if self.result_converter is None:
    169                      self.handler(None, async_result.result)
    170                  else:
    171                      self.handler(None, self.result_converter(async_result.result))
    172              else:
    173                  self.handler(async_result.exception, None)
    174
    175 -class FileSystem(object):
    176      """Represents the file-system and contains a broad set of operations for manipulating files.
    177      An asynchronous and a synchronous version of each operation is provided.
    178      The asynchronous versions take a handler as a final argument which is
    179      called when the operation completes or an error occurs. The handler is called
    180      with two arguments; the first an exception, this will be nil if the operation has
    181      succeeded. The second is the result - this will be nil if the operation failed or
    182      there was no result to return.
    183      The synchronous versions return the results, or throw exceptions directly."""
    184
    185      @staticmethod
    186 -    def java_file_system():
    187          return org.vertx.java.deploy.impl.VertxLocator.vertx.fileSystem()
    188
    189      @staticmethod
    190 -    def copy(frm, to, handler):
    191          """Copy a file, asynchronously. The copy will fail if from does not exist, or if to already exists.
    192
    193          Keyword arguments:
    194          @param frm: path of file to copy
    195          @param to: path of file to copy to
    196          @param handler: the handler which is called on completion."""
    197          FileSystem.java_file_system().copy(frm, to, FSWrappedHandler(handler))
    198
    199      @staticmethod
    200 -    def copy_sync(frm, to):
    201          """Synchronous version of FileSystem.copy"""
    202          FileSystem.java_file_system().copySync(frm, to)
    203
    204      @staticmethod
    205 -    def copy_recursive(frm, to, handler):
    206          """Copy a file recursively, asynchronously. The copy will fail if from does not exist, or if to already exists and is not empty.
    207          If the source is a directory all contents of the directory will be copied recursively, i.e. the entire directory
    208          tree is copied.
    209
    210          Keyword arguments:
    211          @param frm: path of file to copy
    212          @param to: path of file to copy to
    213          @param handler: the function to call when complete
    214          """
    215          FileSystem.java_file_system().copy(frm, to, True, FSWrappedHandler(handler))
    216
    217      @staticmethod
    218 -    def copy_recursive_sync(frm, to):
    219          """Synchronous version of FileSystem.copy_recursive"""
    220          FileSystem.java_file_system().copySync(frm, to, True)
    221
    222      @staticmethod
    223 -    def move(frm, to, handler):
    224          """Move a file, asynchronously. The move will fail if from does not exist, or if to already exists.
    225
    226          Keyword arguments:
    227          @param frm: Path of file to move
    228          @param to: Path of file to move to
    229          @param handler: the function to call when complete
    230          """
    231          FileSystem.java_file_system().move(frm, to, FSWrappedHandler(handler))
    232
    233      @staticmethod
    234 -    def move_sync(frm, to):
    235          """Synchronous version of FileSystem.move"""
    236          FileSystem.java_file_system().moveSync(frm, to)
    237
    238      @staticmethod
    239 -    def truncate(path, len, handler):
    240          """Truncate a file, asynchronously. The move will fail if path does not exist.
    241
    242          Keyword arguments:
    243          @param path: Path of file to truncate
    244          @param len: Length to truncate file to. Will fail if len < 0. If len > file size then will do nothing.
    245          @param handler: the function to call when complete
    246          """
    247          FileSystem.java_file_system().truncate(path, len, FSWrappedHandler(handler))
    248
    249      @staticmethod
    250 -    def truncate_sync(path, len):
    251          """Synchronous version of FileSystem.truncate"""
    252          FileSystem.java_file_system().truncateSync(path, len)
    253
    254      @staticmethod
    255 -    def chmod(path, perms, dir_perms=None, handler=None):
    256          """Change the permissions on a file, asynchronously. If the file is directory then all contents will also have their permissions changed recursively.
    257
    258          Keyword arguments:
    259          @param path: path of file to change permissions
    260          @param perms: a permission string of the form rwxr-x--- as specified in http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html. This is
    261          used to set the permissions for any regular files (not directories).
    262          @param dir_perms: a permission string of the form rwxr-x---. Used to set permissions for regular files.
    263          @param handler: the function to call when complete
    264          """
    265          FileSystem.java_file_system().chmod(path, perms, dir_perms, FSWrappedHandler(handler))
    266
    267      @staticmethod
    268 -    def chmod_sync(path, perms, dir_perms=None):
    269          """Synchronous version of FileSystem.chmod"""
    270          FileSystem.java_file_system().chmodSync(path, perms, dir_perms)
    271
    272      @staticmethod
    273 -    def props(path, handler):
    274          """Get file properties for a file, asynchronously.
    275
    276          Keyword arguments:
    277          @param path: path to file
    278          @param handler: the function to call when complete
    279          """
    280          def converter(obj):
    281              return FileProps(obj)
    282          return FileSystem.java_file_system().props(path, FSWrappedHandler(handler, converter))
    283
    284      @staticmethod
    285 -    def props_sync(path):
    286          """Synchronous version of FileSystem.props"""
    287          java_obj = FileSystem.java_file_system().propsSync(path)
    288          return FileProps(java_obj)
    289
    290      @staticmethod
    291 -    def link(link, existing, handler):
    292          """Create a hard link, asynchronously..
    293
    294          Keyword arguments:
    295          @param link: path of the link to create.
    296          @param existing: path of where the link points to.
    297          @param handler: the function to call when complete
    298          """
    299          FileSystem.java_file_system().link(link, existing, FSWrappedHandler(handler))
    300
    301
    302      @staticmethod
    303 -    def link_sync(link, existing):
    304          """Synchronous version of FileSystem.link"""
    305          FileSystem.java_file_system().linkSync(link, existing)
    306
    307      @staticmethod
    308 -    def sym_link(link, existing, handler):
    309          """Create a symbolic link, asynchronously.
    310
    311          Keyword arguments:
    312          @param link: Path of the link to create.
    313          @param existing: Path of where the link points to.
    314          @param handler: the function to call when complete
    315          """
    316          FileSystem.java_file_system().symLink(link, existing, FSWrappedHandler(handler))
    317
    318      @staticmethod
    319 -    def sym_link_sync(link, existing):
    320          """Synchronous version of FileSystem.sym_link"""
    321          FileSystem.java_file_system().symLinkSync(link, existing)
    322
    323      @staticmethod
    324 -    def unlink(link, handler):
    325          """Unlink a hard link.
    326
    327          Keyword arguments:
    328          @param link: path of the link to unlink.
    329          """
    330          FileSystem.java_file_system().unlink(link, FSWrappedHandler(handler))
    331
    332      @staticmethod
    333 -    def unlinkSync(link):
    334          """Synchronous version of FileSystem.unlink"""
    335          FileSystem.java_file_system().unlinkSync(link)
    336
    337      @staticmethod
    338 -    def read_sym_link(link, handler):
    339          """Read a symbolic link, asynchronously. I.e. tells you where the symbolic link points.
    340
    341          Keyword arguments:
    342          @param link: path of the link to read.
    343          @param handler: the function to call when complete
    344          """
    345          FileSystem.java_file_system().readSymLink(link, FSWrappedHandler(handler))
    346
    347      @staticmethod
    348 -    def read_sym_link_sync(link):
    349          """Synchronous version of FileSystem.read_sym_link"""
    350          FileSystem.java_file_system().readSymLinkSync(link)
    351
    352      @staticmethod
    353 -    def delete(path, handler):
    354          """Delete a file on the file system, asynchronously.
    355          The delete will fail if the file does not exist, or is a directory and is not empty.
    356
    357          Keyword arguments:
    358          @param path: path of the file to delete.
    359          @param handler: the function to call when complete
    360          """
    361          FileSystem.java_file_system().delete(path, FSWrappedHandler(handler))
    362
    363      @staticmethod
    364 -    def delete_sync(path):
    365          """Synchronous version of FileSystem.delete"""
    366          FileSystem.java_file_system().deleteSync(path)
    367
    368      @staticmethod
    369 -    def delete_recursive(path, handler):
    370          """Delete a file on the file system recursively, asynchronously.
    371          The delete will fail if the file does not exist. If the file is a directory the entire directory contents
    372          will be deleted recursively.
    373
    374          Keyword arguments:
    375          @param path: path of the file to delete.
    376          @param handler: the function to call when complete
    377          """
    378          FileSystem.java_file_system().delete(path, True, FSWrappedHandler(handler))
    379
    380      @staticmethod
    381 -    def delete_recursive_sync(path):
    382          """Synchronous version of FileSystem.delete_recursive"""
    383          FileSystem.java_file_system().deleteSync(path, true)
    384
    385      @staticmethod
    386 -    def mkdir(path, perms=None, handler=None):
    387          """Create a directory, asynchronously.
    388          The create will fail if the directory already exists, or if it contains parent directories which do not already
    389          exist.
    390
    391          Keyword arguments:
    392          @param path: path of the directory to create.
    393          @param perms: a permission string of the form rwxr-x--- to give directory.
    394          @param handler: the function to call when complete
    395          """
    396          FileSystem.java_file_system().mkdir(path, perms, FSWrappedHandler(handler))
    397
    398      @staticmethod
    399 -    def mkdir_sync(path, perms=None):
    400          """Synchronous version of FileSystem.mkdir"""
    401          FileSystem.java_file_system().mkdirSync(path, perms)
    402
    403      @staticmethod
    404 -    def mkdir_with_parents(path, perms=None, handler=None):
    405          """Create a directory, and create all it's parent directories if they do not already exist, asynchronously.
    406          The create will fail if the directory already exists.
    407
    408          Keyword arguments:
    409          @param path: path of the directory to create.
    410          @param perms: a permission string of the form rwxr-x--- to give the created directory(ies).
    411          """
    412          FileSystem.java_file_system().mkdir(path, perms, True, FSWrappedHandler(handler))
    413
    414      @staticmethod
    415 -    def mkdir_with_parents_sync(path, perms=None):
    416          """Synchronous version of FileSystem.mkdir_with_parents"""
    417          FileSystem.java_file_system().mkdirSync(path, perms, true)
    418
    419      @staticmethod
    420 -    def read_dir(path, filter=None, handler=None):
    421          """Read a directory, i.e. list it's contents, asynchronously.
    422          The read will fail if the directory does not exist.
    423
    424          Keyword arguments:
    425          @param path: path of the directory to read.
    426          @param filter: a regular expression to filter out the contents of the directory. If the filter is not nil
    427          then only files which match the filter will be returned.
    428          @param handler: the function to call when complete
    429          """
    430          FileSystem.java_file_system().readDir(path, filter, FSWrappedHandler(handler))
    431
    432      @staticmethod
    433 -    def read_dir_sync(path, filter=None):
    434          """Synchronous version of FileSystem.read_dir"""
    435          FileSystem.java_file_system().readDirSync(path, filter)
    436
    437      @staticmethod
    438 -    def read_file_as_buffer(path, handler):
    439          """Read the contents of an entire file as a Buffer, asynchronously.
    440
    441          Keyword arguments:
    442          @param path: path of the file to read.
    443          @param handler: the function to call when complete
    444          """
    445          def converter(buffer):
    446              return Buffer(buffer)
    447          FileSystem.java_file_system().readFile(path, FSWrappedHandler(handler, converter))
    448
    449      @staticmethod
    450 -    def read_file_as_buffer_sync(path):
    451          """Synchronous version of FileSystem.read_file_as_buffer"""
    452          FileSystem.java_file_system().readFileSync(path)
    453
    454      @staticmethod
    455 -    def write_buffer_to_file(path, buffer, handler):
    456          """Write a  as the entire contents of a file, asynchronously.
    457
    458          Keyword arguments:
    459          @param path: path of the file to write.
    460          @param buffer: the Buffer to write
    461          @param handler: the function to call when complete
    462          """
    463          FileSystem.java_file_system().writeFile(path, buffer, FSWrappedHandler(handler))
    464
    465      @staticmethod
    466 -    def write_buffer_to_file_sync(path, buffer):
    467          """Synchronous version of FileSystem.write_buffer_to_file"""
    468          FileSystem.java_file_system().writeFileSync(path, buffer)
    469
    470      @staticmethod
    471 -    def open(path, perms=None, read=True, write=True, create_new=True, flush=False, handler=None):
    472          """Open a file on the file system, asynchronously.
    473
    474          Keyword arguments:
    475          @param path: path of the file to open.
    476          @param perms: if the file does not exist and create_new is true, then the file will be created with these permissions.
    477          @param read: open the file for reading?
    478          @param write: open the file for writing?
    479          @param create_new: Create the file if it doesn't already exist?
    480          @param flush: whenever any data is written to the file, flush all changes to permanent storage immediately?
    481          @param handler: the function to call when complete
    482          """
    483          def converter(file):
    484              return AsyncFile(file)
    485          FileSystem.java_file_system().open(path, perms, read, write, create_new, flush, FSWrappedHandler(handler, converter))
    486
    487      @staticmethod
    488 -    def open_sync(path, perms=None, read=True, write=True, create_new=True, flush=False):
    489          """Synchronous version of FileSystem.open"""
    490          java_obj = FileSystem.java_file_system().open(path, perms, read, write, create_new, flush)
    491          return AsyncFile(java_obj)
    492
    493      @staticmethod
    494 -    def create_file(path, perms=None, handler=None):
    495          """Create a new empty file, asynchronously.
    496
    497          Keyword arguments:
    498          @param path: path of the file to create.
    499          @param perms: the file will be created with these permissions.
    500          @param handler: the function to call when complete
    501          """
    502          FileSystem.java_file_system().createFile(path, perms, FSWrappedHandler(handler))
    503
    504      @staticmethod
    505 -    def create_file_sync(path, perms=None):
    506          """Synchronous version of FileSystem.create_file"""
    507          FileSystem.java_file_system().createFileSync(path, perms)
    508
    509      @staticmethod
    510 -    def exists(path, handler):
    511          """Check if  a file exists, asynchronously.
    512
    513          Keyword arguments:
    514          @param path: Path of the file to check.
    515          @param handler: the function to call when complete
    516          """
    517          FileSystem.java_file_system().exists(path, FSWrappedHandler(handler))
    518
    519      @staticmethod
    520 -    def exists_sync(path):
    521          """Synchronous version of FileSystem.exists"""
    522          return FileSystem.java_file_system().existsSync(path)
    523
    524      @staticmethod
    525 -    def fs_props(path, handler):
    526          """Get properties for the file system, asynchronously.
    527
    528          Keyword arguments:
    529          @param path: Path in the file system.
    530          @param handler: the function to call when complete
    531          """
    532          def converter(props):
    533              return FSProps(props)
    534          FileSystem.java_file_system().fsProps(path, FSWrappedHandler(handler, converter))
    535
    536      @staticmethod
    537 -    def fs_props_sync(path):
    538          """Synchronous version of FileSystem.fs_props"""
    539          j_fsprops = FileSystem.java_file_system().fsPropsSync(path)
    540          return FSProps(j_fsprops)
    541