From a1183b8046623b9ea9ba4383dc7ba627a0c07123 Mon Sep 17 00:00:00 2001 From: Philip Top Date: Wed, 25 Dec 2024 08:56:16 -0800 Subject: [PATCH] add additional python documentation --- .github/workflows/tests.yml | 6 +++++ CMakeLists.txt | 2 +- azure-pipelines.yml | 2 +- docs/installation/index.rst | 9 +++++++ docs/introduction/testing.rst | 22 +++++++++++++--- docs/user-guide/python.rst | 49 +++++++++++++++++++++++++++++++++++ 6 files changed, 84 insertions(+), 6 deletions(-) create mode 100644 docs/user-guide/python.rst diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index e22c074f..f43e0dea 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -184,4 +184,10 @@ jobs: uses: ./.github/actions/quick_cmake with: cmake-version: "3.30" + if: success() || failure() + + - name: Check CMake 3.31 + uses: ./.github/actions/quick_cmake + with: + cmake-version: "3.31" if: success() || failure() \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 0febea7c..1b8c082b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -23,7 +23,7 @@ endif() project( ${UNITS_CMAKE_PROJECT_NAME} LANGUAGES C CXX - VERSION 0.10.2 + VERSION 0.11.0 ) include(CMakeDependentOption) include(CTest) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 382ae0ee..1120778a 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -59,7 +59,7 @@ jobs: units.std: 11 Windowslatest: vmImage: 'windows-2022' - units.std: 20 + units.std: 23 units.options: -DCMAKE_CXX_FLAGS="/std:c++latest" pool: vmImage: $(vmImage) diff --git a/docs/installation/index.rst b/docs/installation/index.rst index e124a6ec..04fffb04 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -19,6 +19,15 @@ Standalone Library ------------------- The units library can be built as a standalone library with either the static or shared library and installed like a typical package. +Python Library +----------------- + +As of version 0.11.0 the library is also available as a python package through pypi. The name of the Python library is `units-llnl` + +.. code-block:: sh + + pip install units-llnl + .. toctree:: :maxdepth: 1 diff --git a/docs/introduction/testing.rst b/docs/introduction/testing.rst index a97c9551..2108846e 100644 --- a/docs/introduction/testing.rst +++ b/docs/introduction/testing.rst @@ -31,6 +31,9 @@ The units library has a series of units tests that are executed as part of the C 19. `test_google_units` run some checks to ensure support for many units supported by google unit translation 20. `test_math` run some tests on the extra mathematical operations found in `units_math.hpp` 21. `test_siunits` run some tests of SI specific units and prefixes +22. `examples_test_windows` test interference or conflicts with any windows headers of MACROS, *only runs on windows* +23. `test_r20` test the recommendation 20 library for conversions and consistency +24. `test_complete_unit_list` run test on a full listing of units @@ -45,27 +48,34 @@ Azure 1. AppleClang 11.0 (Xcode 11.3) C++11 1. MSVC 2019 C++17 1. MSVC 2019 C++11 +1. MSVC 2019 C++14 32-bit 1. MSVC 2022 C++20 1. GCC 4.8 C++11 1. GCC 7 C++11 1. GCC 7 C++14 +1. GCC 7 C++17 1. GCC 8 C++17 1. GCC 9 C++17 1. GCC 12 C++20 +1. GCC 13 C++20 1. Clang 3.4 C++11 1. Clang 3.5 C++11 1. Clang 8 C++14 1. Clang 9 C++17 1. Clang 14 C++20 +1. Clang 16 C++20 +1. Clang 18 C++23 1. Clang-tidy (both main library and tests) Circle-CI ----------- -1. Clang 14, Thread Sanitizer -2. Clang 14, Address, undefined behavior sanitizer -3. Clang 14, Memory Sanitizer -4. Clang 8, Fuzzing library -- run a couple of defined fuzzing tests from scratch to check for any anomalous situations. There are currently two fuzzers, the first test the units_from_string, and the second tests the measurement_from string. It first converts the fuzzing sequence, then if it is a valid sequence, converts it to a string, then converts that string back to a measurement or unit and makes sure the two measurements or units are identical. Any string sequence which doesn't work is captured and tested. +1. Clang 19, Thread Sanitizer [currently disabled due to changes in linux core operations that cannot be changed on CI systems] +1. Clang 19, Address, undefined behavior sanitizer +1. Clang 19, Memory Sanitizer [currently disabled due to changes in linux core operations that cannot be changed on CI systems] +1. Clang 8, Fuzzing library -- run a couple of defined fuzzing tests from scratch to check for any anomalous situations. There are currently two fuzzers, the first test the units_from_string, and the second tests the measurement_from string. It first converts the fuzzing sequence, then if it is a valid sequence, converts it to a string, then converts that string back to a measurement or unit and makes sure the two measurements or units are identical. Any string sequence which doesn't work is captured and tested. +1. Install test +1. Install test with alternate project name GitHub Actions ---------------- @@ -74,6 +84,10 @@ GitHub Actions 1. Coverage (ubuntu 22.04 image C++11, C++14, C++17, C++20, 32 and 64 bit unit base) 1. CPPLINT 1. Quick CMAKE checks for all supported versions of cmake +1. Pip install test for python along with pytest scripts +1. Wheel builder to test different wheels for python packaging + + Codecov ---------- diff --git a/docs/user-guide/python.rst b/docs/user-guide/python.rst new file mode 100644 index 00000000..da2deb39 --- /dev/null +++ b/docs/user-guide/python.rst @@ -0,0 +1,49 @@ +================== +Python +================== +The Python wrapper for the units library is a simplified version of the library. It is focused on the string operations of the library and conversions between units and measurements. + +The units library is available through a pypi package + +.. code-block:: sh + + pip install units-llnl + +Usage +----------- + +.. code-block:: python + + from units_llnl import Unit + + u1 = Unit('m') + u2 = Unit('s') + u3=u1/u2 + speed=20 + desired='mph' + # convert the unit to miles per hour + result = u3.convert(speed,desired) + print(f"{20} {u3} = {result} {desired}") + +This will print a result `20 m/s = 44.73872584108805 mph` + +.. code-block:: python + + from units_llnl import Measurement + + m1 = Measurement('220 m') + m2 = Measurement('11 s') + m3=m1/m2 + desired='mph' + # convert the unit to miles per hour + result = m3.convert_to(desired) + print(f"{m3} = {result}") + +This will produce `20 m/s = 44.7387258411 mph` + +See the pypi_ for a complete description of all methods and functions + +.. _pypi: https://pypi.org/project/units-llnl/ + +Future expansions will include uncertain units and some additional math operations on measurements +