| Name | niltype JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | https://github.com/tsv1/niltype |
| Summary | A singleton Nil object to represent missing values when None is a valid data value |
| upload_time | 2024-09-21 15:21:53 |
| maintainer | None |
| docs_url | None |
| author | Nikita Tsvetkov |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NilType
[](https://codecov.io/gh/tsv1/niltype)
[](https://pypi.python.org/pypi/niltype/)
[](https://pypi.python.org/pypi/niltype/)
[](https://pypi.python.org/pypi/niltype/)
**NilType** is a Python package that provides a `Nil` singleton object to represent a null or missing value in situations where `None` is a valid data value and cannot be used to signify the absence of data. This is especially useful in data models or functions where `None` might be a meaningful value, and a distinct placeholder is needed to indicate 'no value' or 'missing data'.
## Installation
Install `niltype` using pip:
```sh
pip3 install niltype
```
## Introduction
In Python, `None` is often used to represent the absence of a value. However, there are cases where `None` is a valid and meaningful value within your data model. In such situations, you need a different sentinel value to represent 'no value' or 'missing data'. This is where `NilType` comes into play by providing a `Nil` object.
## Usage
### Importing Nil
First, import `Nil` from the `niltype` package:
```python
from niltype import Nil
```
### Checking for Nil
You can check if a variable is `Nil` using the `is` operator:
```python
if x is Nil:
# x is missing or undefined
pass
```
This check will only be `True` if `x` is exactly `Nil`.
### Example Usage
Here's an example of using `Nil` to provide a default value in a function:
```python
from niltype import Nil
def get(dictionary, key, default=Nil):
try:
return dictionary[key]
except KeyError:
if default is not Nil:
return default
raise
# Example usages:
get({}, 'key') # Raises KeyError because no default is provided
get({}, 'key', None) # Returns None
get({}, 'key', 'default') # Returns 'default'
```
In this example, the `get` function behaves similarly to `dict.get()`, but it raises a `KeyError` if the key is not found and no default value is provided. By using `Nil` as the default default value, you can distinguish between when a default has been provided (`None` or any other value) and when it hasn't.
### Nil and Truthiness
The `Nil` object evaluates to `False` in boolean contexts:
```python
if not Nil:
print("Nil is Falsey") # This will print
```
### Using Nil in Type Annotations
You can use the `Nilable` type to indicate that a variable can be either a specific type or `Nil`:
```python
from niltype import Nilable
def process(value: Nilable[int]) -> None:
if value is Nil:
print("Value is missing")
else:
print(f"Value is {value}")
process(10) # Output: Value is 10
process(Nil) # Output: Value is missing
```
The `Nilable` type is a type alias that allows for a value of type `_T` or `NilType`, providing better type hints and checks when using type annotations.
## When to Use Nil
Use `Nil` when you need a unique sentinel value to represent missing or undefined data, especially in the following scenarios:
- **Default Parameters**: Distinguish between an explicit `None` and an unspecified parameter.
- **Data Models**: When `None` is a valid value within your data model, and you need to represent the absence of a value.
- **Optional Values**: Clearly indicate optional values without overloading `None`.
Raw data
{
"_id": null,
"home_page": "https://github.com/tsv1/niltype",
"name": "niltype",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Nikita Tsvetkov",
"author_email": "tsv1@fastmail.com",
"download_url": "https://files.pythonhosted.org/packages/9c/33/ce45c90efcf7f951de4fb1e6032fcb5447b1796c951d86e33324fcff2491/niltype-1.0.2.tar.gz",
"platform": null,
"description": "# NilType\n\n[](https://codecov.io/gh/tsv1/niltype)\n[](https://pypi.python.org/pypi/niltype/)\n[](https://pypi.python.org/pypi/niltype/)\n[](https://pypi.python.org/pypi/niltype/)\n\n**NilType** is a Python package that provides a `Nil` singleton object to represent a null or missing value in situations where `None` is a valid data value and cannot be used to signify the absence of data. This is especially useful in data models or functions where `None` might be a meaningful value, and a distinct placeholder is needed to indicate 'no value' or 'missing data'.\n\n## Installation\n\nInstall `niltype` using pip:\n\n```sh\npip3 install niltype\n```\n\n## Introduction\n\nIn Python, `None` is often used to represent the absence of a value. However, there are cases where `None` is a valid and meaningful value within your data model. In such situations, you need a different sentinel value to represent 'no value' or 'missing data'. This is where `NilType` comes into play by providing a `Nil` object.\n\n## Usage\n\n### Importing Nil\n\nFirst, import `Nil` from the `niltype` package:\n\n```python\nfrom niltype import Nil\n```\n\n### Checking for Nil\n\nYou can check if a variable is `Nil` using the `is` operator:\n\n```python\nif x is Nil:\n # x is missing or undefined\n pass\n```\n\nThis check will only be `True` if `x` is exactly `Nil`.\n\n### Example Usage\n\nHere's an example of using `Nil` to provide a default value in a function:\n\n```python\nfrom niltype import Nil\n\ndef get(dictionary, key, default=Nil):\n try:\n return dictionary[key]\n except KeyError:\n if default is not Nil:\n return default\n raise\n\n# Example usages:\nget({}, 'key') # Raises KeyError because no default is provided\nget({}, 'key', None) # Returns None\nget({}, 'key', 'default') # Returns 'default'\n```\n\nIn this example, the `get` function behaves similarly to `dict.get()`, but it raises a `KeyError` if the key is not found and no default value is provided. By using `Nil` as the default default value, you can distinguish between when a default has been provided (`None` or any other value) and when it hasn't.\n\n### Nil and Truthiness\n\nThe `Nil` object evaluates to `False` in boolean contexts:\n\n```python\nif not Nil:\n print(\"Nil is Falsey\") # This will print\n```\n\n### Using Nil in Type Annotations\n\nYou can use the `Nilable` type to indicate that a variable can be either a specific type or `Nil`:\n\n```python\nfrom niltype import Nilable\n\ndef process(value: Nilable[int]) -> None:\n if value is Nil:\n print(\"Value is missing\")\n else:\n print(f\"Value is {value}\")\n\nprocess(10) # Output: Value is 10\nprocess(Nil) # Output: Value is missing\n```\n\nThe `Nilable` type is a type alias that allows for a value of type `_T` or `NilType`, providing better type hints and checks when using type annotations.\n\n## When to Use Nil\n\nUse `Nil` when you need a unique sentinel value to represent missing or undefined data, especially in the following scenarios:\n\n- **Default Parameters**: Distinguish between an explicit `None` and an unspecified parameter.\n- **Data Models**: When `None` is a valid value within your data model, and you need to represent the absence of a value.\n- **Optional Values**: Clearly indicate optional values without overloading `None`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A singleton Nil object to represent missing values when None is a valid data value",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/tsv1/niltype"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41d2d3dee14b063ce2ce641a5f6d40b3537622373678c9db9ccbe67d15029b13",
"md5": "f88d03888334cbe1fd35a166308066ff",
"sha256": "d5a26b50bb212689e3812a5010e8294d16bd7a179dbd051418ee878bad549754"
},
"downloads": -1,
"filename": "niltype-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f88d03888334cbe1fd35a166308066ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5256,
"upload_time": "2024-09-21T15:21:52",
"upload_time_iso_8601": "2024-09-21T15:21:52.840177Z",
"url": "https://files.pythonhosted.org/packages/41/d2/d3dee14b063ce2ce641a5f6d40b3537622373678c9db9ccbe67d15029b13/niltype-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c33ce45c90efcf7f951de4fb1e6032fcb5447b1796c951d86e33324fcff2491",
"md5": "e91565b29d254bd1083d8431fb531bad",
"sha256": "82bf705a898552467a393a95f3c750d82cd7c9361705c79f4cf416aeaa50b817"
},
"downloads": -1,
"filename": "niltype-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e91565b29d254bd1083d8431fb531bad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5123,
"upload_time": "2024-09-21T15:21:53",
"upload_time_iso_8601": "2024-09-21T15:21:53.669756Z",
"url": "https://files.pythonhosted.org/packages/9c/33/ce45c90efcf7f951de4fb1e6032fcb5447b1796c951d86e33324fcff2491/niltype-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-21 15:21:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsv1",
"github_project": "niltype",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "niltype"
}
