Metadata-Version: 2.4
Name: libstring_util
Version: 1.3.0
Summary: Python packaging wrapper for the libstring_util C library
Author-email: Florian Schmidt <florian.schmidt@dlr.de>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/links_and_nodes/libstring_util
Project-URL: Repository, https://gitlab.com/links_and_nodes/libstring_util
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
Dynamic: license-file

# contents

* simple string operations:
 * string_replace(heystack, needle, repl) -> string
 * [{r,l}]strip(input, white="\r\n\t ") -> string
 * format_string(printf_format, args...) -> string
 * split_string(input, by, max=0) -> vector<string>
 * join_string(vector<string> input, string by) -> string

* (de-)serialization to python source
```C++
    py_value* v = eval_full("[123, 123.456, 'string']");
    printf("python repr: %s\n", repr(v).c_str());
    // output: python repr: [123, 123.456, 'string']
```
check `test/example/example.cpp`
   
# building

libstring_util has at least these build requirements:

 * g++
 * make
 
on debian (tested on jessie):

    $ apt-get install build-essential

## generate build system
if there is no file named "configure" you will need to generate the
autotools-based build-system first. for that you will need these
additional requirements:

 * autoconf (e.g. 2.69-8)
 * automake (e.g. 1.14)
 * libtool (e.g. 2.4.2-1.11)

on debian:

    $ apt-get install automake libtool

to create the buildsystem go into this directory and execute:

    $ autoreconf -if

this will generate a configure-file.

## configure build system
you should build out of source tree. for that create a new directory
and execute configure with your desired flags (try `--help` to see a
list of possible options):

    $ mkdir build
    $ cd build
    $ ../configure --prefix=/usr/local

## start build
after configure successfully finished, you can call make to build the
libstring_util library:

    $ make -j4
	
on success the generated libraries can be found at `build/src/.libs/`

## run test cases

    $ make check


## install
if you want to install the generated libraries to your system (to the
above specified `--prefix`) you can use the `install` target:

    $ make install

depending on where you want to install, you might need root-rights:

    $ sudo make install


# Python packaging

You can install libstringutil from PyPi using `pip install libstring-util`.

libstring_util ships a Python wrapper (`python_pkg/`) that builds the C
library via autotools during `pip install` and installs the compiled `.so`
and public headers into `site-packages/libstring_util/{lib,include}`.

The version is managed from a single source of truth: `project.properties`.


## Quick start

```bash
# Install the package (builds the C library on-the-fly)
# You can pass -vv to activate verbose mode
uv pip install .

# Locate the installed library and headers
python -m libstring_util lib
python -m libstring_util include

# Or programmatically
python -c "import libstring_util; print(libstring_util.list_library_files())"
```


## Testing the packaging locally

All commands below use [`uv`](https://github.com/astral-sh/uv) (install via
`curl -LsSf https://astral.sh/uv/install.sh | sh`).


### Full manylinux wheel build (matches CI)

Requires Docker. Reads `[tool.cibuildwheel]` from `pyproject.toml`.

```bash
# Build all Python versions (3.10–3.14)
uvx --python 3.12 cibuildwheel --platform linux

# Or a single version
CIBW_BUILD="cp312-manylinux_x86_64" uvx cibuildwheel --platform linux
```

Wheels land in `wheelhouse/`.


### Quick smoke test (no Docker)

```bash
# Build a platform-specific wheel
uvx --from build pyproject-build --wheel --outdir dist/

# Install into a fresh uv-managed venv
uv venv /tmp/test_venv
uv pip install --python /tmp/test_venv/bin/python dist/*.whl

# Smoke-check the installed package
/tmp/test_venv/bin/python -m libstring_util lib
/tmp/test_venv/bin/python -m libstring_util include
/tmp/test_venv/bin/python -c "import libstring_util; print(libstring_util.list_library_files())"
```


### Test sdist round-trip

```bash
uvx --from build pyproject-build --sdist --outdir dist/
tar xzf dist/libstring_util-*.tar.gz -C /tmp/
uv pip install --python /tmp/test_venv/bin/python /tmp/libstring_util-*/
```


### Verify wheel content

```bash
unzip -l wheelhouse/*.whl | grep -E '\.so|libstring_util'
```


### Upload to PyPI (wheels + sdist)

The following produces **all** artifacts (manylinux wheels for every Python
version **plus** a source distribution) in a single `dist/` directory, then
uploads them with `twine`.

#### 1. Build manylinux wheels

Requires Docker. Reads `[tool.cibuildwheel]` from `pyproject.toml`.

```bash
uvx --python 3.12 cibuildwheel --platform linux --output-dir dist/
```

#### 2. Build the source distribution

```bash
uvx --from build pyproject-build --sdist --outdir dist/
```

#### 3. Check the artifacts

```bash
ls -lh dist/
# Expect: one .whl per Python version (cp310, cp311, cp312, cp313, cp314)
#         one .tar.gz (source distribution)
```

#### 4. Upload to TestPyPI (dry run, uses a separate token)

```bash
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="pypi-<your-testpypi-token>"

uv tool run --from twine twine upload --repository testpypi dist/*
```

Visit <https://test.pypi.org/project/libstring_util/> to verify the listing.

#### 5. Upload to production PyPI

```bash
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="pypi-<your-production-token>"

uv tool run --from twine twine upload dist/*
```

> **Token setup:** Generate API tokens at
> <https://pypi.org/manage/account/token/> (production) and
> <https://test.pypi.org/manage/account/token/> (TestPyPI).
> Never hardcode tokens — always use environment variables or a `.netrc` file.
