Part of bzrlib.transport View In Hierarchy
Known subclasses: bzrlib.tests.test_store.MockTransport, bzrlib.tests.test_transport.BackupTransportHandler, bzrlib.tests.test_transport.BadTransportHandler, bzrlib.transport.ConnectedTransport, bzrlib.transport.decorator.TransportDecorator, bzrlib.transport.local.LocalTransport, bzrlib.transport.memory.MemoryTransport, bzrlib.transport.pathfilter.PathFilteringTransport, bzrlib.transport.remote.HintingSSHTransport
Most functions have a _multi variant, which allows you to queue up multiple requests. They generally have a dumb base implementation which just iterates over the arguments, but smart Transport implementations can do pipelining. In general implementations should support having a generator or a list as an argument (ie always iterate, never index)
Instance Variables | base | Base URL for the transport; should always end in a slash. |
Method | __init__ | Undocumented |
Method | clone | Return a new Transport object, cloned from the current location, |
Method | create_prefix | Create all the directories leading down to self.base. |
Method | ensure_base | Ensure that the directory this transport references exists. |
Method | external_url | Return a URL for self that can be given to an external process. |
Method | get_segment_parameters | Return the segment parameters for the top segment of the URL. |
Method | abspath | Return the full url to the given relative path. |
Method | recommended_page_size | Return the recommended page size for this transport. |
Method | relpath | Return the local path portion from a given absolute path. |
Method | local_abspath | Return the absolute path on the local filesystem. |
Method | has | Does the file relpath exist? |
Method | has_multi | Return True/False for each entry in relpaths |
Method | has_any | Return True if any of the paths exist. |
Method | iter_files_recursive | Iter the relative paths of files in the transports sub-tree. |
Method | get | Get the file at the given relative path. |
Method | get_bytes | Get a raw string of the bytes for a file at the given location. |
Method | get_smart_medium | Return a smart client medium for this transport if possible. |
Method | readv | Get parts of the file at the given relative path. |
Method | get_multi | Get a list of file-like objects, one for each entry in relpaths. |
Method | put_bytes | Atomically put the supplied bytes into the given location. |
Method | put_bytes_non_atomic | Copy the string into the target location. |
Method | put_file | Copy the file-like object into the location. |
Method | put_file_non_atomic | Copy the file-like object into the target location. |
Method | mkdir | Create a directory at the given path. |
Method | mkdir_multi | Create a group of directories |
Method | open_write_stream | Open a writable file stream at relpath. |
Method | append_file | Append bytes from a file-like object to a file at relpath. |
Method | append_bytes | Append bytes to a file at relpath. |
Method | append_multi | Append the text in each file-like or string object to |
Method | copy | Copy the item at rel_from to the location at rel_to. |
Method | copy_multi | Copy a bunch of entries. |
Method | copy_to | Copy a set of entries from self into another Transport. |
Method | copy_tree | Copy a subtree from one relpath to another. |
Method | copy_tree_to_transport | Copy a subtree from one transport to another. |
Method | rename | Rename a file or directory. |
Method | move | Move the item at rel_from to the location at rel_to. |
Method | move_multi | Move a bunch of entries. |
Method | move_multi_to | Move a bunch of entries to a single location. |
Method | delete | Delete the item at relpath |
Method | delete_multi | Queue up a bunch of deletes to be done. |
Method | delete_tree | Delete an entire tree. This may require a listable transport. |
Method | __repr__ | Undocumented |
Method | stat | Return the stat information for a file. |
Method | rmdir | Remove a directory at the given path. |
Method | stat_multi | Stat multiple files and return the information. |
Method | readlink | Return a string representing the path to which the symbolic link points. |
Method | hardlink | Create a hardlink pointing to source named link_name. |
Method | symlink | Create a symlink pointing to source named link_name. |
Method | listable | Return True if this store supports listing. |
Method | list_dir | Return a list of all files at the given location. |
Method | lock_read | Lock the given file for shared (read) access. |
Method | lock_write | Lock the given file for exclusive (write) access. |
Method | is_readonly | Return true if this connection cannot be written to. |
Method | disconnect | Undocumented |
Method | _translate_error | Translate an IOError or OSError into an appropriate bzr error. |
Method | _pump | Most children will need to copy from one file-like |
Method | _get_total | Try to figure out how many entries are in multi, |
Method | _report_activity | Notify that this transport has activity. |
Method | _update_pb | Update the progress bar based on the current count |
Method | _iterate_over | Iterate over all entries in multi, passing them to func, |
Method | _readv | Get parts of the file at the given relative path. |
Method | _seek_and_read | An implementation of readv that uses fp.seek and fp.read. |
Method | _sort_expand_and_combine | Helper for readv. |
Static Method | _coalesce_offsets | Yield coalesced offsets. |
Method | _can_roundtrip_unix_modebits | Return true if this transport can store and retrieve unix modebits. |
Method | _reuse_for | Undocumented |
Method | _redirected_to | Returns a transport suitable to re-issue a redirected request. |
This handles things like ENOENT, ENOTDIR, EEXIST, and EACCESS
This will create a directory if it doesn't exist. :return: True if the directory was created, False otherwise.
There is no guarantee that the URL can be accessed from a different machine - e.g. file:/// urls are only usable on the local machine, sftp:/// urls when the server is only bound to localhost are only usable from localhost etc.
NOTE: This method may remove security wrappers (e.g. on chroot transports) and thus should only be used when the result will not be used to obtain a new transport within bzrlib. Ideally chroot transports would know enough to cause the external url to be the exact one used that caused the chrooting in the first place, but that is not currently the case.
Returns | A URL that can be given to another process. | |
Raises | InProcessTransport | If the transport is one that cannot be accessed out of the current process (e.g. a MemoryTransport) then InProcessTransport is raised. |
Implementations should call this from all methods that actually do IO. Be careful that it's not called twice, if one method is implemented on top of another.
Parameters | bytes | Number of bytes read or written. |
direction | 'read' or 'write' or None. |
Parameters | expand | If True, the entries will be passed to the function by expanding the tuple. If False, it will be passed as a single parameter. |
Parameters | relpath | a string of a relative path |
This is potentially different for every path in a given namespace. For example, local transports might use an operating system call to get the block size for a given path, which can vary due to mount points.
Returns | The page size in bytes. |
This default implementation is not suitable for filesystems with aliasing, such as that given by symlinks, where a path may not start with our base, but still be a relpath once aliasing is resolved.
This function will only be defined for Transports which have a physical local filesystem representation.
Raises | errors.NotLocalUrl | When no local path representation is available. |
Note that some transports MAY allow querying on directories, but this is not part of the protocol. In other words, the results of t.has("a_directory_name") are undefined.
Returns | (type: bool) |
NOTE: This only lists files, not subdirectories!
As with other listing functions, only some transports implement this,. you may check via listable() to determine if it will.
For correct use of the interface, be sure to catch errors.PathError when calling it and catch errors.ReadError when reading from the returned object.
Parameters | relpath | The relative path to the file |
Returns | (type: File-like object.) |
Parameters | relpath | The relative path to the file |
A smart medium doesn't imply the presence of a smart server: it implies that the smart protocol can be tunnelled via this transport.
Raises | NoSmartMedium | if no smart server medium is available. |
Parameters | relpath | The path to read data from. |
offsets | A list of (offset, size) tuples. | |
adjust_for_latency | Adjust the requested offsets to accomodate transport latency. This may re-order the offsets, expand them to grab adjacent data when there is likely a high cost to requesting data relative to delivering it. | |
upper_limit | When adjust_for_latency is True setting upper_limit allows the caller to tell the transport about the length of the file, so that requests are not issued for ranges beyond the end of the file. This matters because some servers and/or transports error in such a case rather than just satisfying the available ranges. upper_limit should always be provided when adjust_for_latency is True, and should be the size of the file in bytes. | |
Returns | A list or generator of (offset, data) tuples |
Parameters | relpath | The path to read. |
offsets | A list of (offset, size) tuples. | |
Returns | A list or generator of (offset, data) tuples |
This uses _coalesce_offsets to issue larger reads and fewer seeks.
Parameters | fp | A file-like object that supports seek() and read(size). Note that implementations are allowed to call .close() on this file handle, so don't trust that you can use it for other work. |
offsets | A list of offsets to be read from the given file. | |
Returns | yield (pos, data) tuples for each request |
Parameters | offsets | A readv vector - (offset, length) tuples. |
upper_limit | The highest byte offset that may be requested. | |
Returns | A readv vector that will read all the regions requested by offsets, in start-to-end order, with no duplicated regions, expanded by the transports recommended page size. |
With a long list of neighboring requests, combine them into a single large request, while retaining the original offsets. Turns [(15, 10), (25, 10)] => [(15, 20, [(0, 10), (10, 10)])] Note that overlapping requests are not permitted. (So [(15, 10), (20, 10)] will raise a ValueError.) This is because the data we access never overlaps, and it allows callers to trust that we only need any byte of data for 1 request (so nothing needs to be buffered to fulfill a second request.)
Parameters | offsets | A list of (start, length) pairs |
limit | Only combine a maximum of this many pairs Some transports penalize multiple reads more than others, and sometimes it is better to return early. 0 means no limit | |
fudge_factor | All transports have some level of 'it is better to read some more data and throw it away rather than seek', so collapse if we are 'close enough' | |
max_size | Create coalesced offsets no bigger than this size. When a single offset is bigger than 'max_size', it will keep its size and be alone in the coalesced offset. 0 means no maximum size. | |
Returns | return a list of _CoalescedOffset objects, which have members for where to start, how much to read, and how to split those chunks back up |
Parameters | relpaths | A list of relative paths. |
pb | An optional ProgressTask for indicating percent done. | |
Returns | A list or generator of file-like objects |
Parameters | relpath | The location to put the contents, relative to the transport base. |
bytes | A bytestring of data. | |
mode | Create the file with the given mode. | |
Returns | None |
This function is not strictly safe to use. See Transport.put_bytes_non_atomic for more information.
Parameters | relpath | The remote location to put the contents. |
bytes | A string object containing the raw bytes to write into the target file. | |
mode | Possible access permissions for new file. None means do not set remote permissions. | |
create_parent_dir | If we cannot create the target file because the parent directory does not exist, go ahead and create it, and then try again. | |
dir_mode | Possible access permissions for new directories. |
Parameters | relpath | Location to put the contents, relative to base. |
f | File-like object. | |
mode | The mode for the newly created file, None means just use the default. | |
Returns | The length of the file that was written. |
This function is not strictly safe to use. It is only meant to be used when you already know that the target does not exist. It is not safe, because it will open and truncate the remote file. So there may be a time when the file has invalid contents.
Parameters | relpath | The remote location to put the contents. |
f | File-like object. | |
mode | Possible access permissions for new file. None means do not set remote permissions. | |
create_parent_dir | If we cannot create the target file because the parent directory does not exist, go ahead and create it, and then try again. | |
dir_mode | Possible access permissions for new directories. |
A file stream is a file like object with a write() method that accepts bytes to write.. Buffering may occur internally until the stream is closed with stream.close(). Calls to readv or the get_* methods will be synchronised with any internal buffering that may be present.
Parameters | relpath | The relative path to the file. |
mode | The mode for the newly created file, None means just use the default | |
Returns | A FileStream. FileStream objects have two methods, write() and close(). There is no guarantee that data is committed to the file if close() has not been called (even if get() is called on the same path). |
The file is created if it does not already exist.
Parameters | f | a file-like object of the bytes to append. |
mode | Unix mode for newly created files. This is not used for existing files. | |
Returns | the length of relpath before the content was written to it. |
The file is created if it does not already exist.
Parameters | f | a string of the bytes to append. (type: str) |
mode | Unix mode for newly created files. This is not used for existing files. | |
Returns | the length of relpath before the content was written to it. |
Parameters | files | A set of (path, f) entries |
pb | An optional ProgressTask for indicating percent done. |
Override this for efficiency if a specific transport can do it faster than this default implementation.
Parameters | relpaths | A list of tuples of the form [(from, to), (from, to),...] |
Copy a set of entries from self into another Transport. :param relpaths: A list/generator of entries to be copied. :param mode: This is the target mode for the newly created files TODO: This interface needs to be updated so that the target location can be different from the source location.
If a faster implementation is available, specific transports should implement it.
self.base is used as the source tree root, and to_transport.base is used as the target. to_transport.base must exist (and be a directory).
This must fail if the destination is a nonempty directory - it must not automatically remove it. It should raise DirectoryNotEmpty, or some other PathError if the case can't be specifically detected.
If the destination is an empty directory or a file this function may either fail or succeed, depending on the underlying transport. It should not attempt to remove the destination if overwriting is not the native transport behaviour. If at all possible the transport should ensure that the rename either completes or not, without leaving the destination deleted and the new file not moved in place.
This is intended mainly for use in implementing LockDir.
The destination is deleted if possible, even if it's a non-empty directory tree.
If a transport can directly implement this it is suggested that it do so for efficiency.
Parameters | relpaths | A list of tuples of the form [(from1, to1), (from2, to2),...] |
Parameters | relpaths | A list of relative paths [from1, from2, from3, ...] |
rel_to | A directory where each entry should be placed. |
WARNING: many transports do not support this, so trying avoid using it. These methods may be removed in the future.
Transports may raise TransportNotPossible if OS-level locks cannot be taken over this transport.
Returns | A lock object, which should contain an unlock() function. |
WARNING: many transports do not support this, so trying avoid using it. These methods may be removed in the future.
Transports may raise TransportNotPossible if OS-level locks cannot be taken over this transport.
Returns | A lock object, which should contain an unlock() function. |
(For example, 0700 to make a directory owner-private.)
Note: most callers will not want to switch on this, but should rather just try and set permissions and let them be either stored or not. This is intended mainly for the use of the test suite.
Warning: this is not guaranteed to be accurate as sometimes we can't be sure: for example with vfat mounted on unix, or a windows sftp server.
The redirection can be handled only if the relpath involved is not renamed by the redirection.
Parameters | source | The source url as returned by the server. |
target | The target url as returned by the server. | |
Returns | A transport or None. |