valarpy.metamodel

Module Contents

class valarpy.metamodel.EnumField(max_length=255, *args, **kwargs)

A MySQL ENUM field type.

class valarpy.metamodel.BinaryField(max_length=255, *args, **kwargs)

A MySQL constant-width BINARY field type.

class valarpy.metamodel.UnknownField(*_, **__)

A field type that was not recognized.

class valarpy.metamodel.TableDescriptionFrame(data=None, index: Axes | None = None, columns: Axes | None = None, dtype: Dtype | None = None, copy: bool | None = None)

A Pandas DataFrame subclass that contains the columns:

- keys name (str)
- type (str)
- length (int or None)
- nullable (bool)
- choices (set or list)
- primary (bool)
- unique (bool)
- constraints (list of constraint objects)
class valarpy.metamodel.BaseModel(*args, **kwargs)

A table model in Valar through Valarpy and peewee. Provides functions in additional to the normal peewee functions.

get_data() → Dict[str, Any]

Gets a dict of all the fields.

Examples

Users.get(Users.id == 1).get_data() # {‘id’: 2, ‘username’: ‘john’, …}

Returns

The value of every field (column value)

property sstring → str

Gets a short string of the ID. This can be overridden.

Returns

A string like s12

classmethod get_desc_list() → List[Dict[str, str]]

Gets info about the columns as a list of dicts.

Returns

A list the columns in this table, where each is a dictionary of:

- keys name (str)
- type (str)
- nullable (bool)
- choices (set or list)
- primary (bool)
- unique (bool)
- constraints (list of constraint objects)

Return type

list of dicts

classmethod get_desc() → TableDescriptionFrame

Gets a description of this table as a Pandas DataFrame.

Examples

Users.get_desc()

Returns

A TableDescriptionFrame (Pandas DataFrame subclass) of the columns:

- keys name (str)
- type (str)
- length (int or None)
- nullable (bool)
- choices (set or list)
- primary (bool)
- unique (bool)
- constraints (list of constraint objects)

Return type

A DataFrame

classmethod get_schema() → str

Gets the approximate schema string.

Returns

A string that is approximately the text returned by the SQL SHOW CREATE TABLE tablename

classmethod list_where(*wheres: Sequence[peewee.Expression], **values: peewee.Mapping[str, Any])

Runs a simple query and returns a list.

Parameters

  • wheres – List of Peewee WHERE expressions (like Users.id==1) to be joined by AND

  • values – Explicit values (like id=1), also joined by AND

Returns

The table rows in a list

classmethod fetch_or_none(thing: Union[numbers.Integral, str, peewee.Model], like: bool = False, regex: bool = False) → Optional[peewee.Model]
Gets the first (which is unique) match of the row by:

  • instance of this class (just returns it)

  • id columns (if thing is an integer-like type)

  • any of this class’s unique string columns;

    more specifically, a column that is marked in SQL as both (VARCHAR, CHAR, or ENUM) and UNIQUE

Also see fetch, which raises an error if then row was not found.

Examples

# assuming John has ID 2 user = Users.fetch(‘john’) print(user) # Users(2)

Parameters

  • thing – A string, int that

  • like – Use a LIKE expression and wrap in % %

  • regex – Treat thing as a regex pattern

Returns

The Peewee row instance that was found OR None if it does not exist

Raises

  • ValarTableTypeError – If thing is an instance of BaseModel of the wrong type (not this class)

  • TypeError – If thing was not a str, int-like, or a BaseModel

classmethod fetch(thing: Union[numbers.Integral, str, peewee.Model], like: bool = False, regex: bool = False) → peewee.Model
Gets the first (which is unique) match of the row by:

  • instance of this class (just returns it)

  • id columns (if thing is an integer-like type

  • any of this class’s unique string columns; more specifically, a column that is marked in SQL as both (VARCHAR, CHAR, or ENUM) and UNIQUE

Also see fetch_or_none, which returns None if the row was not found.

Examples

# assuming John has ID 2 user = Users.fetch(‘john’) print(user) # Users(2)

Parameters

  • thing – A string, int that

  • like – Use a LIKE expression and wrap in % %

  • regex – Treat thing as a regex pattern

Returns

The matching Peewee row instance

Raises

  • ValarLookupError – If the row was not found

  • ValarTableTypeError – If thing is an instance of BaseModel of the wrong type (not this class)

  • TypeError – If thing was not a str, int-like, or a BaseModel

classmethod fetch_all(things: Iterable[Union[numbers.Integral, str, peewee.Model]]) → Sequence[peewee.Model]

Fetches rows corresponding to things from their instances, IDs, or values from unique columns. See fetch for full information. Also see fetch_all_or_none for a similar function. This method is preferrable to calling fetch repeatedly because it minimizes the number of queries. Specifically, it will perform 0, 1, or 2 queries depending on the passed types:

- If only instances are passed, it just returns them (0 queries)
- If only IDs or only string values are passed, it performs 1 query
- If both IDs and string values are passed, it performs 2 queries

Examples

# assuming John has ID 2 and Alex has user ID 14 users = Users.fetch_all([‘john’, 14, ‘john’, Users.get(Users.id == 2)]) print(users) # [Users(2), Users(14), Users(2), Users(2)]

Returns

A sequence of the rows found, in the same order as they were passed

Raises

  • ValarLookupError – If any of the elements of things was not found

  • ValarTableTypeError – If an instance of a BaseModel of the wrong type (not this class) was passed

  • TypeError – If the type of an element was otherwise invalid (not str, BaseModel, or int-like)

classmethod fetch_all_or_none(things: Iterable[Union[numbers.Integral, str, peewee.Model]], join_fn: Optional[peewee.Callable[[peewee.Expression], peewee.Expression]] = None) → Iterable[peewee.Model]

Fetches rows corresponding to things from their instances, IDs, or values from unique columns. See fetch for full information. Also see fetch_all for a similar function. This method is preferrable to calling fetch repeatedly because it minimizes the number of queries. Specifically, it will perform 0, 1, or 2 queries depending on the passed types:

- If only instances are passed, it just returns them (0 queries)
- If only IDs or only string values are passed, it performs 1 query
- If both IDs and string values are passed, it performs 2 queries

Examples

# assuming John has ID 2 and Alex has user ID 14 users = Users.fetch_all_or_none([‘john’, 14, ‘john’, Users.get(Users.id == 2)]) print(users) # [Users(2), Users(14), Users(2), Users(2)]

Returns

A sequence of the rows found, or None if they were not found; in the same order as they were passed

Raises

  • ValarTableTypeError – If an instance of a BaseModel of the wrong type (not this class) was passed

  • TypeError – If the type of an element was otherwise invalid (not str, BaseModel, or int-like)

classmethod fetch_to_query(thing: Union[numbers.Integral, str, peewee.Model, peewee.Expression, Sequence[peewee.Expression], Sequence[Union[numbers.Integral, str, peewee.Model]]]) → Sequence[peewee.Expression]

This method has limited but important reasons for being called. See fetch, fetch_or_none, fetch_all, or fetch_all_or_none for more commonly used functions. Returns a sequence of Peewee expressions corresponding to WHERE statements:

- If the instance is one of (int, str, or model), that the row is the one passed,
  matched by ID or unique column value as needed
- If the instance is a Peewee expression itself, that the expression matches
Parameters

thing –

An int-type to be looked up by the id column, a str. Looked up by:

- a unique column value
- a model instance
- an expression
- a list of expressions

Returns

A sequence of Peewee expressions to be joined with AND

Raises

  • ValarTableTypeError – If thing is an instance of BaseModel of the wrong type (not this class)

  • TypeError – If thing was not a str, int-like, or a BaseModel instance

classmethod get_indexing_cols()

Gets the list of unique columns

Returns

The columns, of course