From b92cf37145d893721c74443391312187f3bce64b Mon Sep 17 00:00:00 2001 From: Vitor Hideyoshi Date: Fri, 20 Jun 2025 23:12:33 -0300 Subject: [PATCH] Adds Docs for Array, Bool and Numeric --- docs/source/usage.array.rst | 86 +++++++++++++++++++++++++ docs/source/usage.bool.rst | 34 ++++++++++ docs/source/usage.numeric.rst | 118 ++++++++++++++++++++++++++++++++++ docs/source/usage.rst | 5 +- 4 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 docs/source/usage.array.rst create mode 100644 docs/source/usage.bool.rst create mode 100644 docs/source/usage.numeric.rst diff --git a/docs/source/usage.array.rst b/docs/source/usage.array.rst new file mode 100644 index 0000000..239da62 --- /dev/null +++ b/docs/source/usage.array.rst @@ -0,0 +1,86 @@ +Array Type +================= + + +The Array type has the following required properties: + +- items: Schema for the items in the array, which can be a type or a schema object. + +And the additional supported properties: + +- maxItems: Maximum number of items in the array. +- minItems: Minimum number of items in the array. +- uniqueItems: If true, all items in the array must be unique. + +And the additional generic properties: + +- default: Default value for the array. +- description: Description of the array field. + + +Examples +----------------- + + +1. Basic Array with maxItems and minItems: + +.. code-block:: python + + from jambo import SchemaConverter + + + schema = { + "title": "ArrayExample", + "type": "object", + "properties": { + "tags": { + "type": "array", + "items": {"type": "string"}, + "minItems": 1, + "maxItems": 5, + }, + }, + "required": ["tags"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(tags=["python", "jambo", "pydantic"]) + print(obj) # Output: ArrayExample(tags=['python', 'jambo', 'pydantic']) + + + try: + obj = Model(tags=[]) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for ArrayExample + + +2. Array with uniqueItems: + +.. code-block:: python + + from jambo import SchemaConverter + + + schema = { + "title": "UniqueArrayExample", + "type": "object", + "properties": { + "unique_tags": { + "type": "array", + "items": {"type": "string"}, + "uniqueItems": True, + }, + }, + "required": ["unique_tags"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(unique_tags=["python", "jambo", "pydantic"]) + print(obj) # Output: UniqueArrayExample(unique_tags={'python', 'jambo', 'pydantic'}) + + try: + obj = Model(unique_tags=["python", "jambo", "python"]) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for UniqueArrayExample diff --git a/docs/source/usage.bool.rst b/docs/source/usage.bool.rst new file mode 100644 index 0000000..5703f57 --- /dev/null +++ b/docs/source/usage.bool.rst @@ -0,0 +1,34 @@ +Bool Types +================= + + +The Bool type has no specific properties, it has only the generic properties: + +- default: Default value for the string. +- description: Description of the string field. + + +Examples +----------------- + + +.. code-block:: python + + from jambo import SchemaConverter + + + schema = { + "title": "BoolExample", + "type": "object", + "properties": { + "is_active": { + "type": "boolean", + }, + }, + "required": ["is_active"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(is_active=True) + print(obj) # Output: BoolExample(is_active=True) \ No newline at end of file diff --git a/docs/source/usage.numeric.rst b/docs/source/usage.numeric.rst new file mode 100644 index 0000000..324b943 --- /dev/null +++ b/docs/source/usage.numeric.rst @@ -0,0 +1,118 @@ +Numeric Types +================= + + +The Numeric Types (integer, number) have the following supported properties: + +- minimum: Minimum value for the number. +- maximum: Maximum value for the number. +- exclusiveMinimum: If true, the value must be greater than the minimum. +- exclusiveMaximum: If true, the value must be less than the maximum. +- multipleOf: The value must be a multiple of this number. + +And the additional generic properties: + +- default: Default value for the string. +- description: Description of the string field. + + +Examples +----------------- + + +1. Basic Integer with minimum and maximum: + +.. code-block:: python + + from jambo import SchemaConverter + + schema = { + "title": "IntegerExample", + "type": "object", + "properties": { + "age": { + "type": "integer", + "minimum": 0, + "maximum": 120, + }, + }, + "required": ["age"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(age=30) + print(obj) # Output: IntegerExample(age=30) + + try: + obj = Model(age=-5) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for IntegerExample + + +2. Number with exclusiveMinimum and exclusiveMaximum: + +.. code-block:: python + + from jambo import SchemaConverter + + schema = { + "title": "NumberExample", + "type": "object", + "properties": { + "price": { + "type": "number", + "exclusiveMinimum": 0, + "exclusiveMaximum": 1000, + }, + }, + "required": ["price"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(price=1) + print(obj) # Output: NumberExample(price=1) + + try: + obj = Model(price=0) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for NumberExample + + + obj = Model(price=999) + print(obj) # Output: NumberExample(price=999) + + try: + obj = Model(price=1000) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for NumberExample + + +3. Number with multipleOf: + +.. code-block:: python + + from jambo import SchemaConverter + + schema = { + "title": "MultipleOfExample", + "type": "object", + "properties": { + "quantity": { + "type": "number", + "multipleOf": 0.5, + }, + }, + "required": ["quantity"], + } + + Model = SchemaConverter.build(schema) + + obj = Model(quantity=2.5) + print(obj) # Output: MultipleOfExample(quantity=2.5) + + try: + obj = Model(quantity=2.3) # This will raise a validation error + except ValueError as e: + print("Validation fails as expected:", e) # Output: Validation fails as expected: 1 validation error for MultipleOfExample diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 1f46f51..92ce265 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -37,4 +37,7 @@ For more complex schemas and types see our documentation on :maxdepth: 2 :caption: Contents: - usage.string \ No newline at end of file + usage.string + usage.numeric + usage.bool + usage.array \ No newline at end of file