basilisp.io

Polymorphic IO functions.

Functions in this namespace can provide readers and writers for both text and binary streams from a wide variety of different input types as well as utility functions for interacting with the filesystem.

protocolCoercions[source]
fn (as-path f)[source]

Coerce f to a pathlib.Path instance.

Callers should generally prefer basilisp.io/path to this function.

protocolIOFactory[source]
fn (make-input-stream f opts)[source]

Coerce f to a binary input stream instance, subject to opts.

Callers should generally prefer input-stream to this function.

fn (make-output-stream f opts)[source]

Coerce f to a binary output stream instance, subject to opts.

Callers should generally prefer output-stream to this function.

fn (make-reader f opts)[source]

Coerce f to a text-based reader instance, subject to opts.

Callers should generally prefer reader to this function.

fn (make-writer f opts)[source]

Coerce f to a text-based writer instance, subject to opts.

Callers should generally prefer writer to this function.

fn (copy input output & opts)[source]

Copy the contents of a file from input to output. Metadata will not be copied.

input may be one of:

output may be one of:

Options include:

keyword :encoding:

used only when converting from binary to text buffers

keyword :buffer-size:

the buffer size of chunks when copying files manually

The default implementation where both arguments are pathlib.Path objects defer to Python’s shutil.copyfile() which provides default fast-path platform-specific implementations wherever available in Python 3.8+.

Additional implementations may be added by providing additional methods (via basilisp.core/defmethod) for the multi-method copy-file.

All default implementations of copy-file do not close any streams save for those which are opened by the implementations.

multi fn (copy-file & args)[source]

Multi-method implementation for copying files.

To register a new implementation, use basilisp.core/defmethod like so:

(defmethod copy-file [python/str python/str]
  [input output opts]
   ...)
fn (delete-file f)[source]
fn (delete-file f silently)

Delete the file named by f.

If silently is false or nil (default), attempting to delete a non-existent file will raise a FileNotFoundError. Otherwise, return the value of silently.

fn (exists? f)[source]

Return true if f exists. f may be any type supported by path.

fn (input-stream f & opts)[source]

Open an input stream instance on the file or path f.

The input stream instances returned are always binary, not text-based. In general, the input streams should be compatible with Python’s io.BufferedIOBase interface.

Callers should take care to open a reader instance using :lpy:fn`basilisp.core/with-open` to ensure that any resources are properly closed afterwards. Note that for in-memory IO buffers such as io.BytesIO and io.StringIO, opening an input stream without assigning it to a name for the duration of its use may trigger garbage collection of the input stream which closes the underlying buffer, discarding the contents and invalidating the buffer.

Default implementations are available for:

fn (make-parents f & others)[source]

Create the parent paths of f if they do not exist. Arguments will be passed to path before creating the parent directories.

fn (output-stream f & opts)[source]

Open an output stream instance on the file or path f.

The output stream instances returned are always binary, not text-based. In general, the output streams should be compatible with Python’s io.BufferedIOBase interface.

Callers should take care to open a writer instance using basilisp.core/with-open to ensure that any resources are properly closed afterwards. Note that for in-memory IO buffers such as io.BytesIO and io.StringIO, opening an output stream without assigning it to a name for the duration of its use may trigger garbage collection of the output stream which closes the underlying buffer, discarding the contents and invalidating the buffer.

Default implementations are available for:

fn (path p)[source]
fn (path parent child)
fn (path parent child & others)

Coerce p to a pathlib.Path instance.

When multiple arguments are provided, treat the first as the parent path and each subsequent argument as a child path, joining all paths together as one.

fn (reader f & opts)[source]

Open a reader instance on the file or path f.

The reader instances returned are always text-based, not binary. In general, the readers should be compatible with Python’s io.TextIOBase interface.

Callers should take care to open a reader instance using basilisp.core/with-open to ensure that any resources are properly closed afterwards. Note that for in-memory IO buffers such as io.BytesIO and io.StringIO, opening a reader without assigning it to a name for the duration of its use may trigger garbage collection of the reader which closes the underlying buffer, discarding the contents and invalidating the buffer.

Default implementations are available for:

fn (touch f)[source]

Create file f if it does not exist. f may be any type supported by path.

fn (writer f & opts)[source]

Open a writer instance on the file or path f.

The writer instances returned are always text-based, not binary. In general, the writers should be compatible with Python’s io.TextIOBase interface.

opts is an optional collection of keyword/value pairs transmitted as a map to the writer. The acceptable keywords align with those recognized by the open function. Moreover, setting the :append option to true will configure the writer for append mode.

Callers should take care to open a writer instance using basilisp.core/with-open to ensure that any resources are properly closed afterwards. Note that for in-memory IO buffers such as io.BytesIO and io.StringIO, opening a writer without assigning it to a name for the duration of its use may trigger garbage collection of the writer which closes the underlying buffer, discarding the contents and invalidating the buffer.

Default implementations are available for: