# Define
[](https://pypi.org/project/define-oc/) 
Define uses JSON as a language independant way to describe data types that can then be validated, and in the case of all strings form data, cleaned up and turned into the appropriate variable type.
## Install
```bash
pip install define-oc
```
## Using
Defining data can be done at runtime with dicts and lists, but one of the advantages of creating definition files in JSON is being able to share them with your front end systems to allow validating data with the same rules in the browser or app before even sending it to the server.
user.json
```json
{
"id": "uuid4",
"email": {
"__type__": "string",
"__regex__": ""
},
"name": {
"first": "string",
"middle": {
"__type__": "string",
"__maximum__": 1,
"__optional__": true
},
"last": "string"
},
"address": {
"line1": "string",
"line2": {
"__type__": "string",
"__optional__": true
},
"city": "string",
"state": {
"__type__": "string",
"__regex__": "[A-Z]{2}"
},
"country": {
"__type__": "string",
"__options__": [ "CA", "MX", "US" ]
}
},
"phone": "string",
"dob": {
"__type__": "date",
"__optional__": true
},
"height": {
"feet": {
"__type__": "uint",
"__maximum__": 7
},
"inches": {
"__type__": "uint",
"__maximum__": 11
},
"__optional__": true
}
}
```
Once defined, the data can be used in Python using the available classes.
user.py
```python
from define import Parent
import json
import sys
# Load the file
definition = {}
with open('user.json', 'r') as f:
definition = json.load(f)
# Create the Parent instance
parent = Parent(definition)
# Test data
data = {
'id': '52cd4b20-ca32-4433-9516-0c8684ec57c2',
'email': 'chris@domain.com',
'name': {
'first': 'Chris',
'last': 'Nasr'
},
'address': {
'line1': '123 Main Street',
'state': 'QC',
'country': 'CA'
},
'phone': '(888) 555-1234',
'height': {
'feet': '5',
'inches': '11'
}
}
if not parent.valid(data):
print(tree.validation_failures)
# [ [ 'address.city', 'missing' ] ]
# Clean the data
data = tree.clean(data)
"""
{ ...
height: {
'feet': 5,
'inches': 11
}
}
"""
```
## Extending
Any fields marked by two leading and trailing underscores is considered a special value and can be accessed using the `special` method. This can be used to add details only relevent to a specific system, either directly, or through the use of classes that inherit the Define classes.
For example, a class that handles storing the data in a database might need extra data to know how to convert the Define type to an equivalent database type, or to limit that type.
user.json
```json
{
...
"name": {
"first": {
"__type__": "string",
"__maximum__": 32,
"__sql_type__": "varchar(32)"
},
"middle": {
"__type__": "string",
"__maximum__": 1,
"__optional__": true,
"__sql_type__": "char(1)"
},
"last": {
"__type__": "string",
"__maximum__": 32,
"__sql_type__": "varchar(32)"
}
},
...
}
```
Or, if we don't want this data in the shared file, we can add it at runtime and let the class merge the two.
user.py
```python
...
# Create the Parent instance
parent = Parent(definition, {
'name': {
'__sql_type__': 'varchar(32)'
},
'middle': {
'__sql_type__': 'char(1)'
},
'last': {
'__sql_type__': 'varchar(32)'
}
})
...
```
Then we can access that data at runtime
```python
...
# Get the SQL type for the first name field
name_first_type = parent['name']['first'].special('sql_type')
```
## Documentation
Full documentation, including information on using Arrays and dynamic Objects, as well as how to handle errors, can be found on [ouroboroscoding.com/define](https://ouroboroscoding.com/define)
Raw data
{
"_id": null,
"home_page": "https://ouroboroscoding.com/format-oc",
"name": "define-oc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "data, format, database, db, sql, nosql",
"author": "Chris Nasr - Ouroboros Coding Inc.",
"author_email": "chris@ouroboroscoding.com",
"download_url": "https://files.pythonhosted.org/packages/9f/94/1ecad405639ddc3e46cc5c4dba43cf14e77524205f7ed6ac42817d7cdd8e/define-oc-1.0.1.tar.gz",
"platform": null,
"description": "# Define\n\n[](https://pypi.org/project/define-oc/) \n\nDefine uses JSON as a language independant way to describe data types that can then be validated, and in the case of all strings form data, cleaned up and turned into the appropriate variable type.\n\n## Install\n```bash\npip install define-oc\n```\n\n## Using\nDefining data can be done at runtime with dicts and lists, but one of the advantages of creating definition files in JSON is being able to share them with your front end systems to allow validating data with the same rules in the browser or app before even sending it to the server.\n\nuser.json\n```json\n{\n\t\"id\": \"uuid4\",\n\t\"email\": {\n\t\t\"__type__\": \"string\",\n\t\t\"__regex__\": \"\"\n\t},\n\t\"name\": {\n\t\t\"first\": \"string\",\n\t\t\"middle\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__maximum__\": 1,\n\t\t\t\"__optional__\": true\n\t\t},\n\t\t\"last\": \"string\"\n\t},\n\t\"address\": {\n\t\t\"line1\": \"string\",\n\t\t\"line2\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__optional__\": true\n\t\t},\n\t\t\"city\": \"string\",\n\t\t\"state\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__regex__\": \"[A-Z]{2}\"\n\t\t},\n\t\t\"country\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__options__\": [ \"CA\", \"MX\", \"US\" ]\n\t\t}\n\t},\n\t\"phone\": \"string\",\n\t\"dob\": {\n\t\t\"__type__\": \"date\",\n\t\t\"__optional__\": true\n\t},\n\t\"height\": {\n\t\t\"feet\": {\n\t\t\t\"__type__\": \"uint\",\n\t\t\t\"__maximum__\": 7\n\t\t},\n\t\t\"inches\": {\n\t\t\t\"__type__\": \"uint\",\n\t\t\t\"__maximum__\": 11\n\t\t},\n\t\t\"__optional__\": true\n\t}\n}\n```\n\nOnce defined, the data can be used in Python using the available classes.\n\nuser.py\n```python\nfrom define import Parent\nimport json\nimport sys\n\n# Load the file\ndefinition = {}\nwith open('user.json', 'r') as f:\n\tdefinition = json.load(f)\n\n# Create the Parent instance\nparent = Parent(definition)\n\n# Test data\ndata = {\n\t'id': '52cd4b20-ca32-4433-9516-0c8684ec57c2',\n\t'email': 'chris@domain.com',\n\t'name': {\n\t\t'first': 'Chris',\n\t\t'last': 'Nasr'\n\t},\n\t'address': {\n\t\t'line1': '123 Main Street',\n\t\t'state': 'QC',\n\t\t'country': 'CA'\n\t},\n\t'phone': '(888) 555-1234',\n\t'height': {\n\t\t'feet': '5',\n\t\t'inches': '11'\n\t}\n}\n\nif not parent.valid(data):\n\tprint(tree.validation_failures)\n\t# [ [ 'address.city', 'missing' ] ]\n\n# Clean the data\ndata = tree.clean(data)\n\"\"\"\n{ ...\n height: {\n 'feet': 5,\n 'inches': 11\n }\n}\n\"\"\"\n```\n\n## Extending\nAny fields marked by two leading and trailing underscores is considered a special value and can be accessed using the `special` method. This can be used to add details only relevent to a specific system, either directly, or through the use of classes that inherit the Define classes.\n\nFor example, a class that handles storing the data in a database might need extra data to know how to convert the Define type to an equivalent database type, or to limit that type.\n\nuser.json\n```json\n{\n\t...\n\t\"name\": {\n\t\t\"first\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__maximum__\": 32,\n\t\t\t\"__sql_type__\": \"varchar(32)\"\n\t\t},\n\t\t\"middle\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__maximum__\": 1,\n\t\t\t\"__optional__\": true,\n\t\t\t\"__sql_type__\": \"char(1)\"\n\t\t},\n\t\t\"last\": {\n\t\t\t\"__type__\": \"string\",\n\t\t\t\"__maximum__\": 32,\n\t\t\t\"__sql_type__\": \"varchar(32)\"\n\t\t}\n\t},\n\t...\n}\n```\n\nOr, if we don't want this data in the shared file, we can add it at runtime and let the class merge the two.\n\nuser.py\n```python\n...\n# Create the Parent instance\nparent = Parent(definition, {\n\t'name': {\n\t\t'__sql_type__': 'varchar(32)'\n\t},\n\t'middle': {\n\t\t'__sql_type__': 'char(1)'\n\t},\n\t'last': {\n\t\t'__sql_type__': 'varchar(32)'\n\t}\n})\n...\n```\n\nThen we can access that data at runtime\n\n```python\n...\n# Get the SQL type for the first name field\nname_first_type = parent['name']['first'].special('sql_type')\n```\n\n## Documentation\nFull documentation, including information on using Arrays and dynamic Objects, as well as how to handle errors, can be found on [ouroboroscoding.com/define](https://ouroboroscoding.com/define)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A system for defining and validating data regardless of data store",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://ouroboroscoding.com/format-oc",
"Homepage": "https://ouroboroscoding.com/format-oc",
"Source": "https://github.com/ouroboroscoding/define-python",
"Tracker": "https://github.com/ouroboroscoding/define-python/issues"
},
"split_keywords": [
"data",
" format",
" database",
" db",
" sql",
" nosql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f941ecad405639ddc3e46cc5c4dba43cf14e77524205f7ed6ac42817d7cdd8e",
"md5": "dc9b127f23a27927cb8dbfc9e1de3c8d",
"sha256": "f90a3f20ccfec14cd7861735b7830e5edd6e4d6a04a41c7c72eb101ebb1252a5"
},
"downloads": -1,
"filename": "define-oc-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "dc9b127f23a27927cb8dbfc9e1de3c8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20939,
"upload_time": "2024-04-10T21:24:14",
"upload_time_iso_8601": "2024-04-10T21:24:14.837820Z",
"url": "https://files.pythonhosted.org/packages/9f/94/1ecad405639ddc3e46cc5c4dba43cf14e77524205f7ed6ac42817d7cdd8e/define-oc-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 21:24:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ouroboroscoding",
"github_project": "define-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "define-oc"
}
JSON
