snakepath

C99 STB-style header-only port of Python's pathlib. Passes CPython 3.12's own test suite. POSIX + Windows. No malloc. Vibe-coded with Claude Code + Cursor.

The original API was created by Antoine Pitrou.

          u=https://raw.githubusercontent.com/netanel-haber/snakepath/main/snakepath.h && \
curl -sSLo snakepath.h "$u" && \
cat <<'EOF' | cc -xc - -o demo &&
#define SP_PATH_MAX 4096
#define SNAKEPATH_FLUENT
#define SNAKEPATH_IMPLEMENTATION
#include "snakepath.h"
#include <stdio.h>

int main(void) {
    SpPath boring = sp_path("/foo/bar.txt");
    printf("BORING API: %s\n", sp_name(&boring).buf);
    printf("BORING API: %s\n", sp_stem(&boring).buf);
    SpPath fluent = SPF("/etc")->join("nginx")->join("nginx.conf")->path();
    printf("FLUENT API: %s\n", sp_str(&fluent));
}
EOF
./demo
rm -f demo snakepath.h
        

Build & Test

cc -o nob nob.c && ./nob

Snakepath API Reference

Boring API

Path Creation

            SpPath p = sp_path("a/b/c");           // Native flavor
SpPath p = sp_path_f("a/b/c", SP_FLAVOR_POSIX);   // Explicit POSIX
SpPath p = sp_path_f("C:/x", SP_FLAVOR_WINDOWS); // Explicit Windows
          

Path Components

            SpTerm name   = sp_name(&p);   // Final component: "file.txt"
SpTerm stem   = sp_stem(&p);   // Name without suffix: "file"
SpTerm suffix = sp_suffix(&p); // Extension: ".txt"
SpTerm drive  = sp_drive(&p);  // Drive letter: "C:" (Windows)
SpTerm root   = sp_root(&p);   // Root: "/" or "\"
SpTerm anchor = sp_anchor(&p); // Drive + root: "C:\"
// SpTerm has .buf (null-terminated) and .len fields
printf("%s\n", name.buf);        // Direct %s usage works!
          

            SpPath parent = sp_parent(&p);  // Parent directory

// Iterate parts
SpPartsIter it = sp_parts_begin(&p);
SpStr part;
while (sp_parts_next(&it, &part)) { /* use part */ }

// Iterate parents
SpParentsIter pit = sp_parents_begin(&p);
SpPath par;
while (sp_parents_next(&pit, &par)) { /* use par */ }
          

Joining

            SpPath joined = sp_join_one(&p, "subdir");
SpPath joined = sp_join(&p, "a", "b", "c");  // C only (variadic)
SpPath joined = sp_joinpath(&p, &other);
          

Modification

            SpPath new_p = sp_with_name(&p, "newfile.txt");
SpPath new_p = sp_with_stem(&p, "newname");
SpPath new_p = sp_with_suffix(&p, ".md");
          

Queries

            bool abs = sp_is_absolute(&p);
bool rel = sp_is_relative_to(&p, &base);
SpPath relative = sp_relative_to(&p, &base);
bool eq = sp_path_eq(&a, &b);
bool ne = sp_path_ne(&a, &b);
bool same = sp_samefile(&a, &b);
          

Glob / Directory Traversal

            // Iterator-based API
SpGlobIter it = sp_glob_begin(&base, "*.txt", SP_CASE_PLATFORM_DEFAULT);
SpPath match;
while (sp_glob_next(&it, &match)) { /* use match */ }
sp_glob_end(&it);

// Recursive glob (prepends **/)
SpGlobIter it = sp_rglob_begin(&base, "*.c", SP_CASE_PLATFORM_DEFAULT);

// Convenient foreach macros
SP_GLOB_FOREACH(&base, "*.txt", match) { /* use match */ }
SP_RGLOB_FOREACH(&base, "*.c", match) { /* use match */ }

// Callback-based walk - allocation-free, unlimited depth
bool my_callback(struct SpWalkEntry *e) {
    printf("%s: %zu dirs, %zu files\n",
           sp_str(&e->dirpath), e->dirname_count, e->filename_count);
    return true;
}
SpPath dir = sp_path("src");
sp_walk(&dir, true, false, my_callback, NULL, NULL);
          

Fluent API

Enable with #define SNAKEPATH_FLUENT before including. All non-iterator, non-mutator methods are available as fluent calls.

            #define SP_PATH_MAX 4096
#define SNAKEPATH_FLUENT
#define SNAKEPATH_IMPLEMENTATION
#include "snakepath.h"

// Path('a/b/c').parent.name -> "b"
SpTerm name = SPF("a/b/c")->parent()->name();

// PurePosixPath('/etc').joinpath('init.d', 'apache2')
SpPath p = SPF_P("/etc")->join("init.d")->join("apache2")->path();

SpPath w = SPF_W("C:/Users")->join("docs")->path();
SpPath child = sp_join_one(&p, "file.txt");
          

Macro	Python
`SPF("path")`	`Path('path')`
`SPF_P("path")`	`PurePosixPath('path')`
`SPF_W("path")`	`PureWindowsPath('path')`
`SPF_PATH(p)`	Start fluent chain from existing `SpPath`

Core Types

            SpStr   { const char *data; size_t len; }  // String view (non-owning)
SpTerm  { char buf[256]; size_t len; }           // Terminated string (owning, null-terminated)
SpPath  { char buf[4096]; size_t len; SpFlavor flavor; }
SpFlavor { SP_FLAVOR_NATIVE, SP_FLAVOR_POSIX, SP_FLAVOR_WINDOWS }
          

SpTerm vs SpStr: Component functions (name, stem, suffix, drive, root, anchor) return SpTerm which owns its data and is null-terminated, allowing direct %s usage. SpStr is a view into existing memory (used internally and for iteration).

Configuration

Define before including:

            #define SP_PATH_MAX 4096      // Max path length (REQUIRED)
#define SP_MAX_SUFFIXES 16    // Max file extensions (optional)
          

Note: SP_PATH_MAX must be defined before including the header. Use SP_PATH_MAX_LINUX (4096) or SP_PATH_MAX_WINDOWS (1024) as guidance.

Platform Behavior

	POSIX	Windows
Separator	`/`	`\` (normalizes `/`)
Drive	None	`C:` or UNC `\\server\share`
Absolute	Has root `/`	Has drive + root `C:\`

Python Bindings

Thin ctypes wrapper providing PurePath, PurePosixPath, and PureWindowsPath classes compatible with Python's pathlib interface.

            from snakepath import PurePosixPath, PureWindowsPath

p = PurePosixPath('/usr/local/bin')
print(p.name)    # 'bin'
print(p.parent)  # PurePosixPath('/usr/local')
print(p.suffix)  # ''

w = PureWindowsPath('C:/Users/test.txt')
print(w.drive)   # 'C:'
print(w.stem)    # 'test'
          

Testing

Tests run CPython’s official pathlib test suite against snakepath:

python tests/python_harness/run_cpython_tests.py

Gotchas

Empty paths normalize to `"."`

Like Python's pathlib, an empty path string normalizes to "." (current directory):

            SpPath p = sp_path("");
printf("%s\n", sp_str(&p));  // prints "."
          

`sp_suffixes()` returns all dot-separated segments

Like Python's pathlib.Path.suffixes, this function returns all segments after dots in the filename—not just "real" file extensions:

            SpPath p = sp_path("snakepath-1.0.0.tar.gz");
SpSuffixes s = sp_suffixes(&p);  // s.count == 4: ".0", ".0", ".tar", ".gz"
          

Use sp_suffix() if you only want the final extension (.gz).

Parent iteration terminates at anchors

sp_parents_count() and parent iteration stop at the path's anchor—/ for absolute paths, . for relative paths:

            sp_parents_count(sp_path("/a/b/c/d")) == 4  // /a/b/c, /a/b, /a, /
sp_parents_count(sp_path("a/b/c"))    == 3  // a/b, a, .
sp_parents_count(sp_path("/"))        == 0  // root has no parents
sp_parents_count(sp_path("."))        == 0  // current dir has no parents
          

Pathlib Mapping

PurePath docs · Path docs

Python	Boring API	Fluent
`.parts`	`sp_parts_begin/next()`	-
`.drive`	`sp_drive()`	`.drive()`
`.root`	`sp_root()`	`.root()`
`.anchor`	`sp_anchor()`	`.anchor()`
`.parents`	`sp_parents_begin/next()`	-
`.parent`	`sp_parent()`	`.parent()`
`.name`	`sp_name()`	`.name()`
`.suffix`	`sp_suffix()`	`.suffix()`
`.suffixes`	`sp_suffixes()`	`.suffixes()`
`.stem`	`sp_stem()`	`.stem()`
`.as_posix()`	`sp_as_posix()`	-
`.is_absolute()`	`sp_is_absolute()`	`.is_absolute()`
`.is_relative_to()`	`sp_is_relative_to()`	`.is_relative_to()`
`.joinpath()`	`sp_join_one()`	`.join()`
`.match()`	`sp_match()`	-
`.relative_to()`	`sp_relative_to()`	`.relative_to()`
`.with_name()`	`sp_with_name()`	`.with_name()`
`.with_stem()`	`sp_with_stem()`	`.with_stem()`
`.with_suffix()`	`sp_with_suffix()`	`.with_suffix()`
`__eq__`	`sp_path_eq()`	`.eq()`
`__ne__`	`sp_path_ne()`	`.ne()`
`.absolute()`	`sp_absolute()`	`.absolute()`
`.as_uri()`	`sp_as_uri()`	-
`Path.cwd()`	`sp_cwd()`	-
`Path.home()`	`sp_home()`	-
`.expanduser()`	`sp_expanduser()`	`.expanduser()`
`.stat()`	`sp_stat()`	-
`.lstat()`	`sp_lstat()`	-
`.exists()`	`sp_exists()`	`.exists()`
`.is_file()`	`sp_is_file()`	`.is_file()`
`.is_dir()`	`sp_is_dir()`	`.is_dir()`
`.is_symlink()`	`sp_is_symlink()`	`.is_symlink()`
`.is_block_device()`	`sp_is_block_device()`	`.is_block_device()`
`.is_char_device()`	`sp_is_char_device()`	`.is_char_device()`
`.is_fifo()`	`sp_is_fifo()`	`.is_fifo()`
`.is_socket()`	`sp_is_socket()`	`.is_socket()`
`.is_mount()`	`sp_is_mount()`	`.is_mount()`
`.is_junction()`	`sp_is_junction()`	`.is_junction()`
`.samefile()`	`sp_samefile()`	`.samefile()`
`.readlink()`	`sp_readlink()`	-
`.resolve()`	`sp_resolve()`	-
`.glob()`	`sp_glob_begin/next/end()`	-
`.rglob()`	`sp_rglob_begin/next/end()`	-
`.iterdir()`	`sp_iterdir_begin/next/end()`	-
`.walk()`	`sp_walk()`	-
`.mkdir()`	`sp_mkdir()`	-
`.touch()`	`sp_touch()`	-
`.unlink()`	`sp_unlink()`	-
`.rmdir()`	`sp_rmdir()`	-
`.rename()`	`sp_rename()`	-
`.replace()`	`sp_replace()`	-
`.chmod()`	`sp_chmod()`	-
`.symlink_to()`	`sp_symlink_to()`	-
`.hardlink_to()`	`sp_hardlink_to()`	-
`.owner()`	`sp_owner()`	`.owner()`
`.group()`	`sp_group()`	`.group()`
`.read_bytes()`	`sp_read_file()`	`.read_file()`
`.read_text()`	`sp_read_file()`	`.read_file()` + decode
`.write_bytes()`	`sp_write_file()`	`.write_file()`
`.write_text()`	`sp_write_file()`	`.write_file()` + encode
`.open()`	-	-

MIT License

Copyright (c) 2026 Netanel Haber Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

snake ascii art that also looks like a path

snakepath

C99 STB-style port of Python's pathlib. Passes CPython's own test suite.

Build & Test

Boring API

Path Creation

Path Components

Navigation

Joining

Modification

Queries

Glob / Directory Traversal

Fluent API

Core Types

Configuration

Platform Behavior

Python Bindings

Testing

Gotchas

Empty paths normalize to `"."`

`sp_suffixes()` returns all dot-separated segments

Parent iteration terminates at anchors

Pathlib Mapping

Build & Test

Boring API

Path Creation

Path Components

Navigation

Joining

Modification

Queries

Glob / Directory Traversal

Fluent API

Core Types

Configuration

Platform Behavior

Python Bindings

Testing

Gotchas

Empty paths normalize to "."

sp_suffixes() returns all dot-separated segments

Parent iteration terminates at anchors

Pathlib Mapping

Empty paths normalize to `"."`

`sp_suffixes()` returns all dot-separated segments