feat: Initial code for xbool.

Release-As: 1.0.0

.github/workflows/publish-docs.yml

@@ -0,0 +1,6 @@
+on: workflow_dispatch
+name: Publish Docs
+jobs:
+  reusable:
+    uses: xyngular/reusable-github-workflows/.github/workflows/py-publish-docs.yml@main
+    secrets: inherit

.github/workflows/push-main.yml

@@ -0,0 +1,11 @@
+on:
+  push:
+    branches:
+      - main
+name: Push Main
+jobs:
+  reusable:
+    uses: xyngular/reusable-github-workflows/.github/workflows/py-push-main.yml@main
+    with:
+      real-publish: true
+    secrets: inherit

.github/workflows/test.yml

@@ -0,0 +1,6 @@
+name: test-local
+on: pull_request
+jobs:
+  reusable:
+    uses: xyngular/reusable-github-workflows/.github/workflows/py-test.yml@main
+    secrets: inherit

.gitignore

@@ -0,0 +1,7 @@
+/.idea
+/build
+/dist
+__pycache__
+/site
+/docs/api/
+

LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright (c) 2022 Xyngular
+
+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.
+
+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.

README.md

@@ -0,0 +1,103 @@
+![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.8|%203.9|%203.10|%203.11&color=blue?style=flat-square&logo=python)
+![PyPI version](https://badge.fury.io/py/xbool.svg?)
+
+- [Introduction](#introduction)
+- [Documentation](#documentation)
+- [Install](#install)
+- [Quick Start](#quick-start)
+    * [bool_value](#bool_value)
+    * [bool_env](#bool_env)
+- [Licensing](#licensing)
+
+# Introduction
+
+General purpose bool/boolean utilities, extracting bools from strings.
+
+Only two so far:
+
+- `bool_value`, see **[bool_value docs](https://xyngular.github.io/py-xbool/latest/)**.
+- `bool_env`, see **[bool_env docs](https://xyngular.github.io/py-xbool/latest/)**.
+
+# Documentation
+
+**[📄 Detailed Documentation](https://xyngular.github.io/py-xbool/latest/)** | **[🐍 PyPi](https://pypi.org/project/xbool/)**
+
+# Install
+
+```bash
+# via pip
+pip install xbool
+
+# via poetry
+poetry add xbool
+```
+
+# Quick Start
+
+## bool_value
+
+Generally converts objects to bool-values, special-casing strings
+to use the built-in `distutils.util.strtobool` function to convert the string value
+to a bool.
+
+```python
+from xbool import bool_value
+
+# Convert string to bool
+assert bool_value('true') is True
+assert bool_value('false') is False
+
+assert bool_value('y') is True
+assert bool_value('n') is False
+
+assert bool_value('on') is True
+assert bool_value('off') is False
+
+assert bool_value('t') is True
+assert bool_value('f') is False
+
+assert bool_value('yes') is True
+assert bool_value('no') is False
+
+assert bool_value('1') is True
+assert bool_value('0') is False
+
+# Any other string is generally considered False:
+assert bool_value("some-other-string") is False
+
+# Convert bools to bools:
+assert bool_value(True) is True
+assert bool_value(False) is False
+
+# Generally, for non-strings, True-like objects return True:
+some_object = object()
+assert bool_value(some_object) is True
+
+# And False-like objects return False:
+assert bool_value(None) is False
+```
+
+## bool_env
+
+Looks up environmental variable with passed in name.
+
+Runs the env-var value though `bool_value` for you and returns the result.
+
+Useful to easily get a bool-value from an environmental variable.
+
+```python
+from xbool import bool_env
+import os
+
+os.environ['SOME_ENV_VAR'] = "False"
+assert bool_env('SOME_ENV_VAR') is False
+
+
+os.environ['SOME_OTHER_ENV_VAR'] = "True"
+assert bool_env('SOME_OTHER_ENV_VAR') is True
+```
+
+
+# Licensing
+
+This library is licensed under the MIT-0 License. See the LICENSE file.

docs/changelog.md

@@ -0,0 +1,4 @@
+[comment]: <> (Includes Changelog content entire file as a snippet)
+<!-- changelog is partially generated, so it doesn't follow headings and required structure, so we disable it. -->
+<!-- markdownlint-disable -->
+--8<-- "CHANGELOG.md"

docs/index.md

@@ -0,0 +1,111 @@
+---
+title: Getting Started
+---
+
+## Install
+
+```bash
+# via pip
+pip install xbool
+
+# via poetry
+poetry add xbool
+```
+
+## Introduction
+
+General purpose bool/boolean utilities, extracting bools from strings.
+
+## bool_value function
+
+Converts any object to a bool.
+
+Special-cases strings, which bool is returned is based on string contents.
+
+```python
+from xbool import bool_value
+
+# Convert string to bool
+assert bool_value('true') is True
+assert bool_value('false') is False
+```
+
+Generally, if the value passed in is one of these, it's considered `True`:
+
+- For Strings (after stripping any leading/training white-space):
+    - "t"
+    - "True"
+    - "T"
+    - "1"
+    - "true"
+    - "on"
+- For `bool`:
+    - We simply return whatever the passed-in bool is.
+- Other Types Of Objects:
+    - If object is True-like (where object's `__bool__()` value is True).
+
+
+Otherwise, a `False` will be returned (ie: if string contains 'false', we return False).
+
+If any `ValueError` is raised while trying to get bool-value from any object,
+will return `False`.
+
+### Examples
+
+```python
+from xbool import bool_value
+
+# Convert string to bool
+assert bool_value('true') is True
+assert bool_value('false') is False
+
+assert bool_value('y') is True
+assert bool_value('n') is False
+
+assert bool_value('on') is True
+assert bool_value('off') is False
+
+assert bool_value('t') is True
+assert bool_value('f') is False
+
+assert bool_value('yes') is True
+assert bool_value('no') is False
+
+assert bool_value('1') is True
+assert bool_value('0') is False
+
+# Any other string is generally considered False:
+assert bool_value("some-other-string") is False
+
+# Convert bools to bools:
+assert bool_value(True) is True
+assert bool_value(False) is False
+
+# Generally, for non-strings, True-like objects return True:
+some_object = object()
+assert bool_value(some_object) is True
+
+# And False-like objects return False:
+assert bool_value(None) is False
+```
+
+
+## bool_env
+
+Looks up environmental variable with passed in name.
+
+Runs the env-var value though `bool_value` for you and returns the result.
+
+Useful to easily get a bool-value from an environmental variable.
+
+```python
+from xbool import bool_env
+import os
+
+os.environ['SOME_ENV_VAR'] = "False"
+assert bool_env('SOME_ENV_VAR') is False
+
+
+os.environ['SOME_OTHER_ENV_VAR'] = "True"
+assert bool_env('SOME_OTHER_ENV_VAR') is True
+```

mkdocs.yml

@@ -0,0 +1,79 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: Docs for xbool
+dev_addr: 127.0.0.1:7000
+
+nav:
+  - xbool:
+    - index.md
+  - API Reference: api/xbool/" target="_blank
+  - Changelog: changelog.md
+
+theme:
+  name: material
+  font:
+    text: Ubuntu
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue grey
+      accent: cyan
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+#    - header.autohide
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+#    - navigation.instant
+    - navigation.indexes
+    - navigation.tracking
+    - content.code.annotate
+  icon:
+    repo: fontawesome/brands/github
+#  logo: media/aws-logo-light.svg
+#  favicon: media/aws-logo-light.svg
+#  custom_dir: docs/overrides
+markdown_extensions:
+  - admonition
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      linenums: true
+  - pymdownx.details
+  - pymdownx.snippets:
+      base_path: "."
+      check_paths: true
+  - meta
+  - toc:
+      permalink: true
+      toc_depth: 4
+  - attr_list
+  - pymdownx.emoji
+  - pymdownx.inlinehilite
+  - pymdownx.superfences:
+
+plugins:
+  - mike:
+      # These fields are all optional; the defaults are as below...
+      alias_type: symlink
+      redirect_template: null
+      deploy_prefix: ''
+      canonical_version: null
+      version_selector: true
+      css_dir: css
+      javascript_dir: js
+  - git-revision-date
+  - search
+extra:
+  version:
+    provider: mike
+    default: latest