README
¶
pathlib
Inspired by Python's pathlib, made better by Golang.
pathlib is an "object-oriented" package for manipulating filesystem path objects. It takes many cues from Python's pathlib, although it does not strictly adhere to its design philosophy. It provides a simple, intuitive, easy, and abstracted interface for dealing with many different types of filesystems.
pathlib is currently in the alpha stage of development, meaning the API is subject to change. However, the current state of the project is already proving to be highly useful.
Table of Contents
Examples
OsFs
Beacuse pathlib treats afero filesystems as first-class citizens, you can instantiate a Path object with the filesystem of your choosing.
Code
package main
import (
"fmt"
"os"
"github.com/chigopher/pathlib"
"github.com/spf13/afero"
)
func main() {
// Create a path on your regular OS filesystem
path := pathlib.NewPathAfero("/home/ltclipp", afero.NewOsFs())
subdirs, err := path.ReadDir()
if err != nil {
fmt.Printf("%v\n", err)
os.Exit(1)
}
for _, dir := range subdirs {
fmt.Println(dir.Name())
}
}
Output
[ltclipp@landon-virtualbox examples]$ go build .
[ltclipp@landon-virtualbox examples]$ ./examples | tail
Music
Pictures
Public
Templates
Videos
git
go
mockery_test
snap
software
In-memory FS
Code
package main
import (
"fmt"
"os"
"github.com/chigopher/pathlib"
"github.com/spf13/afero"
)
func main() {
// Create a path using an in-memory filesystem
path := pathlib.NewPathAfero("/", afero.NewMemMapFs())
hello := path.Join("hello_world.txt")
hello.WriteFile([]byte("hello world!"), 0o644)
subpaths, err := path.ReadDir()
if err != nil {
fmt.Printf("%v\n", err)
os.Exit(1)
}
for _, subpath := range subpaths {
fmt.Printf("Name: %s Mode: %o Size: %d\n", subpath.Name(), subpath.Mode(), subpath.Size())
}
bytes, _ := hello.ReadFile()
fmt.Println(string(bytes))
}
Output
[ltclipp@landon-virtualbox examples]$ go build
[ltclipp@landon-virtualbox examples]$ ./examples
Name: hello_world.txt Mode: 644 Size: 12
hello world!
Design Philosophy
The design philosophy of this package is to be as thin of a layer as possible to existing community-standard packages, like io, afero, and os. Additional functionality is provided in consise and logical ways to extend the existing community APIs.
filepath.Path
The API of filepath.Path can be grouped into a few main categories:
github.com/spf13/afero.Fswrappers: these are methods that have nearly identical signatures toafero.Fs, with the exception of the path string (which is stored in thepathlib.Pathobject itself.afero.Fsis an object that is meant to interact directly with the filesystem.github.com/spf13/afero.Aferowrappers: these are methods that again have nearly identical signatures toafero.Afero.afero.Aferois a convenience object that provides higher-level behavior to the underlyingafero.Fsobject.- Filesystem-specific methods: these are methods that are implemented by some, but not all, of the afero filesystems. These methods may fail at runtime if the filesystem you provide does not implement the required interface.
- Python's Pathlib-inspired methods: these are methods that are not implemented in the previous two steps, and that provide the power behind the object-oriented design.
github.com/chigopher/pathlib-specific methods: these are miscellaneous methods that are not covered by any of the previous categories. These methods are typically conveniences around methods in one of the previous categories.
filepath.File
filepath.File is intended to be a thin wrapper around afero.File. We avoid simply returning this interface on calls to Open() and OpenFile() (etc) because we want the ability to extend our API beyond what afero provides. So, we create our own File object which embeds afero.File, but might possibly contain further functionality.
Frequently Asked Questions
Why pathlib and not filepath?
filepath is a package that is tightly coupled to the OS filesystem APIs and also is not written in an object-oriented way. pathlib uses afero under the hood for its abstracted filesystem interface, which allows you to represent a vast array of different filesystems (e.g. SFTP, HTTP, in-memory, and of course OS filesystems) using the same Path object.
Why not use afero directly?
You certainly could, however afero does not represent a filesystem object in an object-oriented way. It is only object-oriented with respect to the filesystem itself. pathlib is simply a thin layer on top of afero that provides the filesystem-object-orientation.
Does this provide any benefit to my unit tests?
Most certainly! pathlib allows you to create in-memory filesystems, which have the nice property of being automatically garbage collected by Golang's GC when they go out of scope. You don't have to worry about defering any Remove() functions or setting up temporary dirs in /tmp. Just instantiate a MemMapFs and you're good to go!
What filesystems does this support?
Currently only POSIX-style paths are supported.
Documentation
¶
Index ¶
- Variables
- type File
- type Path
- func (p *Path) Chmod(mode os.FileMode) error
- func (p *Path) Chtimes(atime time.Time, mtime time.Time) error
- func (p *Path) Create() (afero.File, error)
- func (p *Path) DirExists() (bool, error)
- func (p *Path) Equals(other *Path) (bool, error)
- func (p *Path) Exists() (bool, error)
- func (p *Path) FileContainsAnyBytes(subslices [][]byte) (bool, error)
- func (p *Path) FileContainsBytes(subslice []byte) (bool, error)
- func (p *Path) Fs() afero.Fs
- func (p *Path) GetLatest() (*Path, error)
- func (p *Path) Glob(pattern string) ([]*Path, error)
- func (p *Path) IsAbsolute() bool
- func (p *Path) IsDir() (bool, error)
- func (p *Path) IsEmpty() (bool, error)
- func (p *Path) IsFile() (bool, error)
- func (p *Path) IsSymlink() (bool, error)
- func (p *Path) Join(elems ...string) *Path
- func (p *Path) Mkdir(perm os.FileMode) error
- func (p *Path) MkdirAll(perm os.FileMode) error
- func (p *Path) Mtime() (time.Time, error)
- func (p *Path) Name() string
- func (p *Path) Open() (*File, error)
- func (p *Path) OpenFile(flag int, perm os.FileMode) (*File, error)
- func (p *Path) Parent() *Path
- func (p *Path) Path() string
- func (p *Path) ReadDir() ([]*Path, error)
- func (p *Path) ReadFile() ([]byte, error)
- func (p *Path) RelativeTo(other *Path) (*Path, error)
- func (p *Path) Remove() error
- func (p *Path) RemoveAll() error
- func (p *Path) Rename(newname string) error
- func (p *Path) RenamePath(target *Path) error
- func (p *Path) Resolve() (*Path, error)
- func (p *Path) SafeWriteReader(r io.Reader) error
- func (p *Path) Stat() (os.FileInfo, error)
- func (p *Path) Symlink(target *Path) error
- func (p *Path) Walk(walkFn filepath.WalkFunc) error
- func (p *Path) WriteFile(data []byte, perm os.FileMode) error
- func (p *Path) WriteReader(r io.Reader) error
Constants ¶
This section is empty.
Variables ¶
var (
ErrDoesNotImplement = errors.Errorf("doesn't implement required interface")
)
Functions ¶
This section is empty.
Types ¶
type File ¶
File represents a file in the filesystem. It inherits the afero.File interface but might also include additional functionality.
type Path ¶
type Path struct {
// DefaultFileMode is the mode that is used when creating new files in functions
// that do not accept os.FileMode as a parameter.
DefaultFileMode os.FileMode
// contains filtered or unexported fields
}
Path is an object that represents a path
func Glob ¶
Glob returns all of the path objects matched by the given pattern inside of the afero filesystem.
func NewPathAfero ¶
NewPathAfero returns a Path object with the given Afero object
func (*Path) Create ¶
Create creates a file if possible, returning the file and an error, if any happens.
func (*Path) DirExists ¶
DirExists returns whether or not the path represents a directory that exists
func (*Path) Equals ¶
Equals returns whether or not the path pointed to by other has the same resolved filepath as self.
func (*Path) FileContainsAnyBytes ¶
FileContainsAnyBytes returns whether or not the path contains any of the listed bytes.
func (*Path) FileContainsBytes ¶
FileContainsBytes returns whether or not the given file contains the bytes
func (*Path) GetLatest ¶
GetLatest returns the file or directory that has the most recent mtime. Only works if this path is a directory and it exists. If the directory is empty, the returned Path object will be nil.
func (*Path) IsAbsolute ¶
IsAbsolute returns whether or not the path is an absolute path. This is determined by checking if the path starts with a slash.
func (*Path) IsSymlink ¶
IsSymlink returns true if the given path is a symlink. Fails if the filesystem doesn't implement afero.Lstater.
func (*Path) Join ¶
Join joins the current object's path with the given elements and returns the resulting Path object.
func (*Path) OpenFile ¶
OpenFile opens a file using the given flags and the given mode. See the list of flags at: https://golang.org/pkg/os/#pkg-constants
func (*Path) ReadDir ¶
ReadDir reads the current path and returns a list of the corresponding Path objects.
func (*Path) ReadFile ¶
ReadFile reads the given path and returns the data. If the file doesn't exist or is a directory, an error is returned.
func (*Path) RelativeTo ¶
RelativeTo computes a relative version of path to the other path. For instance, if the object is /path/to/foo.txt and you provide /path/ as the argment, the returned Path object will represent to/foo.txt.
func (*Path) RenamePath ¶
RenamePath is the same as Rename except the argument is a Path object. The attributes of the path object is retained and does not inherit anything from target.
func (*Path) SafeWriteReader ¶
SafeWriteReader is the same as WriteReader but checks to see if file/directory already exists.
func (*Path) Symlink ¶
Symlink symlinks to the target location. This will fail if the underlying afero filesystem does not implement afero.Linker.
Source Files