The htsql.tr package

htsql.tr

Those are the hills of Hell, my love, Where you and I must go

—(Traditional)

This package implements the HTSQL-to-SQL translator.

htsql.tr.assemble

This module implements the assembling process.

class htsql.tr.assemble.Claim(unit, broker, target)

Represents an export request.

A Claim object represents a request to the broker frame to export a unit from the target frame.

The claim indicates that the SELECT clause of the broker frame must contain a phrase that evaluates the unit.

The target frame must either coincide with the broker frame or be a descendant of the broker frame. When the target and the broker coincide, the broker is responsible for evaluating the unit value. Otherwise, the broker imports the unit value from one of its subframes.

Claim objects are compared by-value. That is, two claim objects are equal if their units, brokers, and targets are equal to each other.

unit (htsql.tr.flow.Unit)
The exported unit.
broker (an integer)
The tag of the broker term/frame. The broker frame is expected to export a phrase corresponding to the given unit.
target (an integer)
The tag of the target term/frame. The target frame is responsible for evaluating the unit. The target term must be a descendant of the broker term or coincide with the broker term.
class htsql.tr.assemble.Gate(is_nullable, dispatches, routes)

Encapsulates a dispatching context.

Dispatching context provides information necessary to demand and supply unit claims.

is_nullable (Boolean)

Indicates that the currently assembled frame is going to be joined to the parent frame using an outer join.

This flag affects the is_nullable indicator of exported phrases.

dispatches (a dictionary tag -> tag)

Maps a descendant term to the immediate child whose subtree contains the term.

The dispatches table is used when generating unit claims to determine the broker term by the target term.

See also the offsprings attribute of htsql.tr.term.Term.

routes (a dictionary Unit | Flow -> tag)

Maps a unit to a term capable of evaluating the unit.

The routes table is used when generating unit claims to determine the target term by the unit.

A key of the routes table is either a htsql.tr.flow.Unit node or a htsql.tr.flow.Flow node. The latter indicates that the corresponding term is capable of exporting any primitive unit from the given flow.

See also the routes attribute of htsql.tr.term.Term.

Note that dispatches and routes come from offsprings and routes attributes of htsql.tr.term.Term. However they do not have to come from the same term! Typically, dispatches comes from the term which is currently translated to a frame, and routes comes either from the same term or from one of its direct children.

class htsql.tr.assemble.AssemblingState

Encapsulates the state of the assembling process.

State attributes:

gate (Gate)
The current dispatching context.
claim_set (a set of Claim)
All requested unit claims.
claims_by_broker (a mapping tag -> [Claim])

Unit claims grouped by the broker.

A key of the mapping is the broker tag. A value of the mapping is a list of Claim objects with the same broker.

phrase_by_claim (a mapping Claim -> Phrase)

Satisfied claims.

A key of the mapping is a Claim object. A value of the mapping is a htsql.tr.frame.ExportPhrase object.

set_tree(term)

Initializes the assembling state.

This method must be called before assembling any frames.

term (htsql.tr.term.SegmentTerm)
The term corresponding to the top-level SELECT statement.
flush()

Clears the assembling state.

push_gate(is_nullable=None, dispatcher=None, router=None)

Updates the current dispatching context.

is_nullable (Boolean or None)

Indicates that the currently assembled frame is to be attached to the parent frame using an OUTER join.

If None, keeps the current value.

When satisfying the claims directed to the currently constructed frame, this flag is used to determine whether the exported values are nullable or not.

dispatcher (htsql.tr.term.Term or None)

Specifies the dispatcher term.

If None, keeps the current dispatcher.

The dispatcher term (more exactly, the offsprings table of the term) maps a descendant term to the immediate child whose subtree contains the term.

When generating claims, the dispatcher is used to find the broker term by the target term.

Typically, the dispatcher term is the one currently translated to a frame node.

router (htsql.tr.term.Term or None)

Specifies the router term.

If None, uses dispatcher as the router term. If both dispatcher and router are None, keeps the current router.

The router term (more exactly, the routes table of the term) maps a unit to a term capable of evaluating the unit.

When generating claims, the router is used to find the target term by the unit.

Typically, the router term is the one currently translated to a frame node or one of its immediate children.

pop_gate()

Restores the previous dispatching context.

assemble(term)

Assembles a frame node for the given term.

term (htsql.tr.term.Term)
A term node.
appoint(unit)

Generates a claim for the given unit.

This method finds the target and the broker terms that are capable of evaluating the unit and returns the corresponding Claim object.

unit (htsql.tr.flow.Unit)
The unit to make a claim for.
forward(claim)

Generates a forward claim for the given claim.

This function takes a claim targeted to one of the current term’s descendants and returns a new claim dispatched to the current term’s immediate child.

claim (Claim)
A claim dispatched to the current term.
schedule(code, dispatcher=None, router=None)

Appoints and assigns claims for all units of the given code.

code (htsql.tr.flow.Code)
A code object to schedule.
dispatcher (htsql.tr.term.Term or None)

Specifies the dispatcher to use when appointing units.

If None, keeps the current dispatcher.

router (htsql.tr.term.Term or None)

Specifies the router to use when appointing units.

If None, uses dispacher as the router term; if both are None, keeps the current router.

evaluate(code, dispatcher=None, router=None)

Evaluates the given code node.

Returns the corresponding htsql.tr.frame.Phrase node.

It is assumed that the code node was previously scheduled with schedule() and all the claims were satisfied.

code (htsql.tr.flow.Code)
The code node to evaluate.
dispatcher (htsql.tr.term.Term or None)

Specifies the dispatcher to use when appointing units.

If None, keeps the current dispatcher.

router (htsql.tr.term.Term or None)

Specifies the router to use when appointing units.

If None uses dispacher as the router term; if both are None, keeps the current router.

demand(claim)

Assigns the given claim to the broker.

claim (Claim)
The claim to assign.
supply(claim, phrase)

Satisfies the claim.

claim (Claim)
The claim to satisfy.
phrase (htsql.tr.frame.Phrase)
The phrase that satisfies the claim.
class htsql.tr.assemble.Assemble(term, state)

Translates a term node to a frame node.

This is an interface adapter, see subclasses for implementations.

The Assemble adapter has the following signature:

Assemble: (Term, AssemblingState) -> Frame

The adapter is polymorphic on the Term argument.

term (htsql.tr.term.Term)
A term node.
state (AssemblingState)
The current state of the assembling process.
class htsql.tr.assemble.AssembleTerm(term, state)

Assembles a frame for a proper term node.

This adapts Assemble for proper term nodes (i.e., not a htsql.tr.term.QueryTerm).

Attributes:

claims (a list of Claim)
The claims that are dispatched to the term.
class htsql.tr.assemble.AssembleScalar(term, state)

Assembles a (scalar) frame for a scalar term.

class htsql.tr.assemble.AssembleTable(term, state)

Assembles a (table) frame for a table term.

class htsql.tr.assemble.AssembleBranch(term, state)

Assembles a branch frame.

This is a default implementation used by all non-terminal (i.e. unary or binary) terms.

class htsql.tr.assemble.AssembleUnary(term, state)

Assembles a frame for an unary term.

This is a default implementation used by all unary terms.

class htsql.tr.assemble.AssembleFilter(term, state)

Assembles a frame for a filter term.

class htsql.tr.assemble.AssembleOrder(term, state)

Assembles a frame for an order term.

class htsql.tr.assemble.AssembleProjection(term, state)

Assembles a frame for a projection term.

class htsql.tr.assemble.AssembleJoin(term, state)

Assembles a frame for a join term.

class htsql.tr.assemble.AssembleEmbedding(term, state)

Assembles a frame for an embedding term.

class htsql.tr.assemble.AssembleCorrelation(term, state)

Assembles a frame for a correlation term.

class htsql.tr.assemble.AssembleSegment(term, state)

Assembles a frame for a segment term.

class htsql.tr.assemble.AssembleQuery(term, state)

Assembles a top-level query frame.

class htsql.tr.assemble.Evaluate(code, state)

Translates a code node to a phrase node.

This is an interface adapter; see subclasses for implementations.

The Evaluate adapter has the following signature:

Evaluate(Code, AssemblingState) -> Phrase

The adapter is polymorphic on the Code argument.

code (htsql.tr.flow.Code)
The code node to translate.
state (AssemblingState)
The current state of the assembling process.
class htsql.tr.assemble.EvaluateLiteral(code, state)

Evaluates a literal code.

class htsql.tr.assemble.EvaluateCast(code, state)

Evaluates a cast code.

class htsql.tr.assemble.EvaluateFormula(code, state)

Evaluates a formula node.

The evaluation could be specific to the formula signature and is implemented by the EvaluateBySignature adapter.

class htsql.tr.assemble.EvaluateBySignature(code, state)

Evaluates a formula node.

This is an auxiliary adapter used to evaluate htsql.tr.flow.FormulaCode nodes. The adapter is polymorphic on the formula signature.

Unless overridden, the adapter evaluates the arguments of the formula and generates a new formula phrase with the same signature.

code (htsql.tr.flow.FormulaCode)
The formula node to evaluate.
state (AssemblingState)
The current state of the assembling process.

Aliases:

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (htsql.tr.domain.Domain)
The co-domain of the formula.
arguments (htsql.tr.signature.Bag)
The arguments of the formula.
class htsql.tr.assemble.EvaluateIsTotallyEqualBase(code, state)

Evaluates the total equality (==) operator.

class htsql.tr.assemble.EvaluateNullIf(code, state)

Evaluates the null_if() operator.

class htsql.tr.assemble.EvaluateIfNull(code, state)

Evaluates the if_null() operator.

class htsql.tr.assemble.EvaluateUnit(code, state)

Evaluates a unit.

htsql.tr.assemble.assemble(term, state=None)

Compiles a new frame node for the given term.

Returns a htsql.tr.frame.Frame instance.

term (htsql.tr.term.Term)
A term node.
state (AssemblingState or None)
The assembling state to use. If not set, a new assembling state is instantiated.

htsql.tr.bind

This module implements the binding process.

class htsql.tr.bind.BindingState

Encapsulates the (mutable) state of the binding process.

State attributes:

root (htsql.tr.binding.RootBinding)
The root naming scope.
scope (htsql.tr.binding.Binding)
The current naming scope.
set_root(root)

Sets the root lookup context.

This function initializes the lookup context stack and must be called before any calls of push_scope() and pop_scope().

root (htsql.tr.binding.RootBinding)
The root lookup scope.
flush()

Clears the lookup scopes.

push_scope(scope)

Sets the new lookup scope.

This function stores the current scope in the stack and makes the given binding the new lookup scope. Use the scope attribute to get the current scope; pop_scope() to restore the previous scope.

scope (htsql.tr.binding.Binding)
The new lookup scope.
pop_scope()

Restores the previous lookup scope.

This functions restores the previous lookup scope from the stack. Use the scope attribute to get the current scope; push_scope() to change the current scope.

bind(syntax, scope=None)

Binds the given syntax node using the current binding state.

Returns a binding node.

syntax (htsql.tr.syntax.Syntax)
The syntax node to bind.
scope (htsql.tr.binding.Binding or None)
If set, the lookup scope is set to scope when binding the syntax node.
use(recipe, syntax, scope=None)

Applies a recipe to produce a binding node.

Returns a binding node.

recipe (htsql.tr.binding.Recipe)
The recipe to apply.
syntax (htsql.tr.syntax.Syntax)
The syntax node associated with the recipe.
scope (htsql.tr.binding.Binding or None)
If set, the lookup scope is set to scope when binding the syntax node.
call(syntax, scope=None)

Binds a global function or a global identifier.

Returns a binding node.

syntax (htsql.tr.syntax.Syntax)
The syntax node to bind.
scope (htsql.tr.binding.Binding or None)
If set, the lookup context is set to scope when binding the syntax node.
class htsql.tr.bind.Bind(syntax, state)

Translates a syntax node to a binding node.

This is an interface adapter; see subclasses for implementations.

The binding process resolves identifiers against database objects, resolves and validates operators and function calls, and determine types of all expression.

The Bind adapter has the following signature:

Bind: (Syntax, BindingState) -> Binding

The adapter is polymorphic on the Syntax argument.

syntax (htsql.tr.syntax.Syntax)
The syntax node to bind.
state (BindingState)
The current state of the binding process.
class htsql.tr.bind.BindByName(syntax, state)

Binds a application node.

This is an abstract protocol interface that provides a mechanism for name-based dispatch of application syntax nodes.

The BindByName interface has the following signature:

BindByName: (ApplicationSyntax, BindingState) -> Binding
BindByName: (IdentifierSyntax, BindingState) -> Binding

The protocol is polymorphic on the name and the number of arguments of the syntax node.

To add an implementation of the interface, define a subclass of BindByName and specify its name and expected number of arguments using function named().

Class attributes:

names (a list of names or pairs (name, length))

List of names the component matches.

Here name is a non-empty string, length is an integer or None, where -1 indicates any number of arguments, None means no arguments are accepted.

class htsql.tr.bind.BindByRecipe(recipe, syntax, state)

Applies a recipe to generate a binding node.

This is an abstract adapter that generates new binding nodes from binding recipes. The BindByRecipe interface has the following signature:

BindByName: (Recipe, Syntax, BindingState) -> Binding

The adapter is polymorphic by the first argument.

recipe (htsql.tr.binding.Recipe)
A recipe to apply.
syntax (htsql.tr.syntax.Syntax)
The syntax node associated with the recipe.
state (BindingState)
The current binding state.
htsql.tr.bind.bind(syntax, state=None, scope=None)

Binds the given syntax node.

syntax (htsql.tr.syntax.Syntax)
The syntax node to bind.
state (BindingState or None).
The binding state to use. If not set, a new binding state is created.
scope (htsql.tr.binding.Binding or None)
If specified, updates the lookup scope when binding the node.

htsql.tr.binding

This module declares binding nodes and recipe objects.

class htsql.tr.binding.Binding(base, domain, syntax)

Represents a binding node.

This is an abstract class; see subclasses for concrete binding nodes.

A binding graph is an intermediate phase of the HTSQL translator between the syntax tree and the flow graph. It is converted from the syntax tree by the binding process and further translated to the flow graph by the encoding process.

The structure of the binding graph reflects the form of naming scopes in the query; each binding node keeps a reference to the scope where it was instantiated.

The constructor arguments:

base (Binding or None)

The scope in which the node is created.

The value of None is only valid for an instance of RootBinding, which represents the origin node in the graph.

domain (htsql.domain.Domain)
The type of the binding node; use htsql.domain.VoidDomain instance when not applicable.
syntax (htsql.tr.syntax.Syntax)
The syntax node that generated the binding node; should be used for presentation or error reporting only, there is no guarantee that that the syntax node is semantically, or even syntaxically valid.

Other attributes:

mark (htsql.mark.Mark)
The location of the node in the original query (for error reporting).
class htsql.tr.binding.Recipe(equality_vector=None)

Represents a recipe object.

A recipe is a generator of binding nodes. Recipes are produced by lookup requests and used to construct the binding graph.

class htsql.tr.binding.QueryBinding(base, segment, syntax)

Represents the whole HTSQL query.

segment (SegmentBinding or None)
The top segment.
class htsql.tr.binding.SegmentBinding(base, seed, elements, syntax)

Represents a segment of an HTSQL query.

seed (Binding or None)
The output flow. If not set explicitly, should be inferred from elements.
elements (a list of Binding)
The output columns.
class htsql.tr.binding.ScopingBinding(base, domain, syntax)

Represents a binding node that introduces a new naming scope.

This is an abstract class; see subclasses for concrete node types.

class htsql.tr.binding.ChainingBinding(base, domain, syntax)

Represents a binding node that augments the parent naming scope.

This is an abstract class; see subclasses for concrete node types.

class htsql.tr.binding.WrappingBinding(base, syntax)

Represents a binding node ignored by the encoder.

This class has subclasses for concrete node types, but could also be used directly to change a syntax node of the parent binding.

class htsql.tr.binding.HomeBinding(base, syntax)

Represents the home naming scope.

The home scope contains links to all tables in the database.

class htsql.tr.binding.RootBinding(syntax)

Represents the root scope.

The root scope is the origin of the binding graph.

class htsql.tr.binding.TableBinding(base, table, syntax)

Represents a table scope.

This is an abstract class; see FreeTableBinding and AttachedTableBinding for concrete subclasses.

A table scope contains all attributes of the tables as well as the links to other tables related via foreign key constraints.

table (htsql.entity.TableEntity)
The table with which the binding is associated.
class htsql.tr.binding.FreeTableBinding(base, table, syntax)

Represents a free table scope.

A free table binding is generated by a link from the home class.

class htsql.tr.binding.AttachedTableBinding(base, join, syntax)

Represents an attached table scope.

An attached table binding is generated by a link from another table.

join (htsql.entity.Join)
The join attaching the table to its base.
class htsql.tr.binding.ColumnBinding(base, column, link, syntax)

Represents a table column scope.

column (htsql.entity.ColumnEntity)
The column entity.
link (Binding or None)
If set, indicates that the binding also represents a link to another table. Any lookup requests applied to the column binding are delegated to link.
class htsql.tr.binding.QuotientBinding(base, seed, kernels, syntax)

Represents a quotient scope.

A quotient expression generates a flow of all unique values of the given kernel as it ranges over the seed flow.

seed (Binding)
The seed of the quotient.
kernels (a list of Binding)
The kernel expressions of the quotient.
class htsql.tr.binding.KernelBinding(base, quotient, index, syntax)

Represents a kernel in a quotient scope.

quotient (QuotientBinding)
The quotient binding (typically coincides with base).
index (an integer)
The position of the selected kernel expression.
class htsql.tr.binding.ComplementBinding(base, quotient, syntax)

Represents a complement link in a quotient scope.

quotient (QuotientBinding)
The quotient binding (typically coincides with base)
class htsql.tr.binding.CoverBinding(base, seed, syntax)

Represents an opaque alias for a scope expression.

seed (Binding)
The covered expression.
class htsql.tr.binding.ForkBinding(base, kernels, syntax)

Represents a forking expression.

kernels (a list of Binding)
The kernel expressions of the fork.
class htsql.tr.binding.LinkBinding(base, seed, images, syntax)

Represents a linking expression.

seed (Binding)
The target of the link.
images (a list of pairs of Binding)
Pairs of expressions connecting seed to base.
class htsql.tr.binding.SieveBinding(base, filter, syntax)

Represents a sieve expression.

A sieve applies a filter to the base binding.

filter (Binding)
A conditional expression that filters the base scope.
class htsql.tr.binding.SortBinding(base, order, limit, offset, syntax)

Represents a sorting expression.

A sort binding specifies the row order for the flow generated by the base binding. It may also apply a slice to the flow.

order (a list of Binding)
The expressions by which the base rows are sorted.
limit (an integer or None)
If set, indicates that only the first limit rows are produced (None means no limit).
offset (an integer or None)
If set, indicates that only the rows starting from offset are produced (None means 0).
class htsql.tr.binding.CastBinding(base, domain, syntax)

Represents a type conversion operation.

domain (htsql.domain.Domain)
The target domain.
class htsql.tr.binding.RescopingBinding(base, scope, syntax)

Represents a rescoping operation.

scope (Binding)
The target scope.
class htsql.tr.binding.AssignmentBinding(base, terms, parameters, body, syntax)

Represents an assignment expression.

terms (a list of pairs (Unicode string, Boolean))

The terms of the assignment.

Each term is represented by a pair of the term name and a flag indicating whether the name is a reference or not.

parameters (a list of pairs (Unicode string, Boolean) or None)

The parameters; if not set, indicates the defined attribute does not accept any parameters.

Each parameter is represented by a pair of the parameter name and a flag indicating whether the name is a reference.

body (htsql.tr.syntax.Syntax)
The body of the assignment.
class htsql.tr.binding.DefinitionBinding(base, name, is_reference, arity, recipe, syntax)

Represents a definition of a calculated attribute or a reference.

name (a Unicode string)
The name of the attribute.
is_reference (Boolean)
If set, indicates a definition of a reference.
arity (an integer or None)
The number of arguments for an parameterized attribute; None for an attribute without parameters.
recipe (Recipe)
The value of the attribute.
class htsql.tr.binding.SelectionBinding(base, elements, syntax)

Represents a selector expression ({...} operator).

A selector specifies output columns of a flow.

elements (a list of Binding)
The output columns.
class htsql.tr.binding.DirectionBinding(base, direction, syntax)

Represents a direction decorator (postfix + and - operators).

direction (+1 or -1).
Indicates the direction; +1 for ascending, -1 for descending.
class htsql.tr.binding.RerouteBinding(base, target, syntax)

Represents a rerouting binding node.

A rerouting node redirects all lookup requests to a designated target.

target (Binding)
The route destination.
class htsql.tr.binding.ReferenceRerouteBinding(base, target, syntax)

Represents a reference rerouting node.

A reference rerouting node redirects reference lookup requests to a designated target.

target (Binding)
The route destination.
class htsql.tr.binding.TitleBinding(base, title, syntax)

Represents a title decorator (the as operator).

The title decorator is used to specify the column title explicitly (by default, a serialized syntax node is used as the title).

title (a Unicode string)
The title.
class htsql.tr.binding.AliasBinding(base, syntax)

Represents a syntax decorator.

The syntax decorator changes the syntax node associated with the base binding node.

class htsql.tr.binding.FormatBinding(base, format, syntax)

Represents a format decorator (the format operator).

The format decorator is used to provide hints to the renderer as to how display column values. How the format is interpreted by the renderer depends on the renderer and the type of the column.

format (a Unicode string)
The formatting hint.
class htsql.tr.binding.LiteralBinding(base, value, domain, syntax)

Represents a literal value.

value (valid type depends on the domain)
The value.
domain (htsql.domain.Domain)
The value type.
class htsql.tr.binding.FormulaBinding(base, signature, domain, syntax, **arguments)

Represents a formula binding.

A formula binding represents a function or an operator call as as a binding node.

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (Domain)
The co-domain of the formula.
arguments (a dictionary)

The arguments of the formula.

Note that all the arguments become attributes of the node object.

class htsql.tr.binding.FreeTableRecipe(table)

Generates a FreeTableBinding node.

table (htsql.entity.TableEntity)
The table associated with the binding.
class htsql.tr.binding.AttachedTableRecipe(joins)

Generates a chain of AttachedTableBinding nodes.

joins (a list of htsql.entity.Join)
The joins to attach the nodes.
origin_table
table entity at the head of this link
target_table
table entity at the tail of this link
is_singular
boolean value if this link is singular
is_direct`
this is single join direct link created by a foreign key
is_reverse
this is a single join created by reversal of a foreign key
class htsql.tr.binding.ColumnRecipe(column, link=None)

Generates a ColumnBinding node.

column (htsql.entity.ColumnEntity)
The column entity.
link (Recipe or None)
If set, indicates that the column also represents a link to another binding node.
class htsql.tr.binding.KernelRecipe(quotient, index)

Generates a KernelBinding node.

quotient (QuotientBinding)
The quotient binding.
index (an integer)
The position of the selected kernel expression.
class htsql.tr.binding.ComplementRecipe(quotient)

Generates a ComplementBinding node.

quotient (QuotientBinding)
The quotient binding.
class htsql.tr.binding.SubstitutionRecipe(base, terms, parameters, body)

Evaluates a calculated attribute or a reference.

base (Binding)
The scope in which the calculation is defined.
terms (a list of pairs (Unicode string, Boolean))
The tail of a qualified definition. Each term is represented by a pair of the term name and a flag indicating whether the term is a reference or not.
parameters (a list of pairs (Unicode string, Boolean) or None)
The parameters of the calculation. Each parameter is a pair of the parameter name and a flag indicating whether the parameter is a reference.
body (htsql.tr.syntax.Syntax)
The body of the calculation.
class htsql.tr.binding.BindingRecipe(binding)

Generates the given node.

binding (Binding)
The node to generate.
class htsql.tr.binding.ClosedRecipe(recipe)

Hides the syntax node of the generated node.

class htsql.tr.binding.PinnedRecipe(scope, recipe)

Evaluates a recipe in the given scope.

base (Binding)
The scope to apply the recipe to.
recipe (Recipe)
The recipe to apply.
class htsql.tr.binding.InvalidRecipe

Generates an error when applied.

class htsql.tr.binding.AmbiguousRecipe

Generates an “ambiguous name” error when applied.

htsql.tr.coerce

This module implements the unary and binary coerce adapters.

class htsql.tr.coerce.UnaryCoerce(domain)

Validates and specializes a domain.

The UnaryCoerce adapter has the following signature:

UnaryCoerce: Domain -> maybe(Domain)

The adapter checks if the given domain is valid. If so, the domain or its specialized version is returned; otherwise, None is returned.

The primary use cases are:

  • disabling special domains in regular expressions;
  • specializing untyped values;
  • providing engine-specific versions of generic domains.

The adapter is rarely used directly, use coerce() instead.

class htsql.tr.coerce.BinaryCoerce(ldomain, rdomain)

Determines a common domain of two domains.

The BinaryCoerce adapter has the following signature:

BinaryCoerce: (Domain, Domain) -> maybe(Domain)

BinaryCoerce is polymorphic on both arguments.

The adapter checks if two domains could be reduced to a single common domains. If the common domain cannot be determined, the adapter returns None.

The primary use cases are:

  • checking if two domains are compatible (that is, if values of these domains are comparable without explicit cast).
  • deducing the actual type of untyped values.

The adapter is rarely used directly, use coerce() instead.

class htsql.tr.coerce.UnaryCoerceSpecial(domain)

Disables special domains.

class htsql.tr.coerce.UnaryCoerceUntyped(domain)

Specializes untyped values.

class htsql.tr.coerce.BinaryCoerceBoolean(ldomain, rdomain)

Coerces untyped values to BooleanDomain.

class htsql.tr.coerce.BinaryCoerceInteger(ldomain, rdomain)

Coerces untyped values to IntegerDomain.

class htsql.tr.coerce.BinaryCoerceDecimal(ldomain, rdomain)

Coerces untyped and integer values to DecimalDomain.

class htsql.tr.coerce.BinaryCoerceFloat(ldomain, rdomain)

Coerces untyped, integer and decimal values to FloatDomain.

class htsql.tr.coerce.BinaryCoerceString(ldomain, rdomain)

Coerces untyped values to StringDomain.

class htsql.tr.coerce.BinaryCoerceEnum(ldomain, rdomain)

Validates and coerces to EnumDomain.

class htsql.tr.coerce.BinaryCoerceDate(ldomain, rdomain)

Coerce to DateDomain.

class htsql.tr.coerce.BinaryCoerceTime(ldomain, rdomain)

Coerce to TimeDomain.

class htsql.tr.coerce.BinaryCoerceDateTime(ldomain, rdomain)

Coerce to DateTimeDomain.

class htsql.tr.coerce.BinaryCoerceOpaque(ldomain, rdomain)

Validate and coerce to OpaqueDomain.

htsql.tr.coerce.coerce(*domains)

Reduces a list of domains to a single common domain.

domains (a list of htsql.domain.Domain)
List of domains.

Returns the most specialized domain covering the given domains; None if the common domain could not be determined.

htsql.tr.compile

This module implements the compiling process.

class htsql.tr.compile.CompilingState

Encapsulates the state of the compiling process.

State attributes:

root (htsql.tr.flow.RootFlow)
The root flow.
baseline (htsql.tr.flow.Flow)
When compiling a new term, indicates the leftmost axis that must exported by the term. Note that the baseline flow is always inflated.
tag()

Generates and returns a new unique term tag.

set_root(flow)

Initializes the root, baseline and mask flows.

This function must be called before state attributes root, baseline and mask could be used.

flow (htsql.tr.flow.RootFlow)
A root scalar flow.
flush()

Clears the state flows.

push_baseline(baseline)

Sets a new baseline flow.

This function masks the current baseline flow. To restore the previous baseline flow, use pop_baseline().

baseline (htsql.tr.flow.Flow)
The new baseline flow. Note that the baseline flow must be inflated.
pop_baseline()

Restores the previous baseline flow.

compile(expression, baseline=None)

Compiles a new term node for the given expression.

expression (htsql.tr.flow.Expression)
An expression node.
baseline (htsql.tr.flow.Flow or None)

The baseline flow. Specifies an axis flow that the compiled term must export. If not set, the current baseline flow of the state is used.

When expression is a flow, the generated term must export the flow itself as well as all inflated prefixes up to the baseline flow. It may (but it is not required) export other axes as well.

inject(term, expressions)

Augments a term to make it capable of producing the given expressions.

This method takes a term node and a list of expressions. It returns a term that could produce the same expressions as the given term, and, in addition, all the given expressions.

Note that, technically, a term only exports unit expressions; we claim that a term could export an expression if it exports all the units of the expression.

term (htsql.tr.term.Term)
A term node.
expressions (a list of htsql.tr.flow.Expression)
A list of expressions to inject into the given term.
class htsql.tr.compile.Compile(expression, state)

Translates an expression node to a term node.

This is an interface adapter; see subclasses for implementations.

The Compile adapter is implemented for two classes of expressions:

  • top-level expressions such as the whole query and the query segment, for which it builds respective top-level term nodes;
  • flows, for which the adapter builds a corresponding relational algebraic expression.

After a term is built, it is typically augmented using the Inject adapter to have it export any exprected units.

The Compile adapter has the following signature:

Compile: (Expression, CompilingState) -> Term

The adapter is polymorphic on the Expression argument.

expression (htsql.tr.flow.Expression)
An expression node.
state (CompilingState)
The current state of the compiling process.
class htsql.tr.compile.Inject(expression, term, state)

Augments a term to make it capable of producing the given expression.

This is an interface adapter; see subclasses for implementations.

This adapter takes a term node and an expression (usually, a unit) and returns a new term (an augmentation of the given term) that is able to produce the given expression.

The Inject adapter has the following signature:

Inject: (Expression, Term, CompilingState) -> Term

The adapter is polymorphic on the Expression argument.

expression (htsql.tr.flow.Expression)
An expression node to inject.
term (htsql.tr.term.Term)
A term node to inject into.
state (CompilingState)
The current state of the compiling process.
class htsql.tr.compile.CompileFlow(flow, state)

Compile a term corresponding to a flow node.

This is an abstract class; see subclasses for implementations.

The general algorithm for compiling a term node for the given flow looks as follows:

  • compile a term for the base flow;
  • inject any necessary expressions;
  • build a new term node that represents the flow operation.

When compiling a term for a flow node, the current baseline flow denotes the leftmost axis that the term should be able to export. The compiler may (but does not have to) omit any axes nested under the baseline axis.

The generated term is not required to respect the ordering of the flow.

Constructor arguments:

flow (htsql.tr.flow.Flow)
A flow node.
state (CompilingState)
The current state of the compiling process.

Other attributes:

backbone (htsql.tr.flow.Flow)
The inflation of the given flow.
baseline (htsql.tr.flow.Flow)
An alias to state.baseline.
htsql.tr.compile.compile(expression, state=None, baseline=None)

Compiles a new term node for the given expression.

Returns a htsql.tr.term.Term instance.

expression (htsql.tr.flow.Expression)
An expression node.
state (CompilingState or None)
The compiling state to use. If not set, a new compiling state is instantiated.
baseline (htsql.tr.flow.Flow or None)
The baseline flow. Specifies an axis that the compiled term must export. If not set, the current baseline flow of the state is used.

htsql.tr.dump

This module implements the SQL serialization process.

class htsql.tr.dump.Stream

Implements a writable file-like object.

Use write() to write a string to the stream. The data is accumulated in an internal buffer of the stream.

Use flush() to get the accumulated content and truncate the stream.

Stream also provides means for automatic indentation. Use indent() to set a new indentation level, dedent() to revert to the previous indentation level, newline() to set the position to the current indentation level.

write(data)

Writes a string to the stream.

newline()

Sets the cursor to the current indentation level.

indent()

Sets the indentation level to the current cursor position.

dedent()

Reverts to the previous indentation level.

flush()

Returns the accumulated content and truncates the stream.

class htsql.tr.dump.Hook(with_aliases)

Encapsulates serializing hints and instructions.

with_aliases (Boolean)
If set, indicates that the generated SELECT clause must contain aliases.
class htsql.tr.dump.SerializingState

Encapsulates the state of the serializing process.

State attributes:

stream (Stream)
A file-like object accumulating the generated SQL statement.
frame_by_tag (a mapping: integer -> htsql.tr.frame.Frame)
Maps the frame tag to the respective frame.
select_aliases_by_tag (a mapping: integer -> a list of aliases)
Maps the frame tag to the list of aliases for the frame SELECT clause.
frame_alias_by_tag (a mapping: integer -> an alias)
Maps the frame tag to the alias of the frame.
hook (Hook)
Encapsulates serializing hints and directives.
set_tree(frame)

Initializes the serializing state.

This method must be called before dumping any clauses.

frame (htsql.tr.frame.SegmentFrame)
The term corresponding to the top-level SELECT statement.
push_hook(with_aliases)

Updates serializing directives.

with_aliases (Boolean)
If set, indicates that the SELECT clause must have aliases.
pop_hook()

Restores the previous serializing directives.

flush()

Clears the serializing state and returns the generated SQL.

serialize(clause)

Serializes the given clause.

clause (htsql.tr.frame.Clause)
The clause to serialize.
dump(clause)

Writes SQL for the given clause.

clause (htsql.tr.frame.Clause)
The clause to dump.
dub(clause)

Generates a preform alias for the given clause.

clause (htsql.tr.frame.Clause)
The clause to generate an alias for.
class htsql.tr.dump.Serialize(clause, state)

Translates a clause to SQL.

This is an interface adapter; see subclasses for implementations.

The Serialize has the following signature:

Serialize: (Clause, SerializingState) -> SQL

The adapter is polymorphic on the Clause argument.

clause (htsql.tr.frame.Clause)
The clause to serialize.
state (SerializingState)
The current state of the serializing process.
class htsql.tr.dump.SerializeQuery(clause, state)

Serializes an HTSQL query to an execution plan.

class htsql.tr.dump.SerializeSegment(clause, state)

Serializes an HTSQL segment to SQL.

Class attributes:

max_alias_length (an integer)
The maximum length of an alias.
aliasing(frame=None, taken_select_aliases=None, taken_include_aliases=None)

Generates SELECT and FROM aliases.

frame (htsql.tr.frame.BranchFrame or None)
The frame to generate aliases for.
taken_select_aliases (a set or None)
The SELECT aliases to avoid. Note that aliasing() may update the collection.
taken_include_aliases (a set of None)
The FROM aliases to avoid. Note that aliasing() may update the collection.
class htsql.tr.dump.DumpBase(clause, state)

Translates a clause node to SQL.

This is a base class for the family of Dump adapters; it encapsulates methods and attributes shared between these adapters.

A Dump adapter generates a SQL expression for the given frame or phrase clause node and writes it to the stream that accumulates a SQL statement.

clause (htsql.tr.frame.Clause)
A clause to serialize.
state (SerializingState)
The current state of the serializing process.
format(template, *namespaces, **keywords)

Serializes a set of variables according to a template.

The format() method expects a template string containing variable fields denoted by {}. The method writes the string to the SQL stream replacing variables with respective values.

The format of the variable fields is:

{name}
{name:kind}
{name:kind{modifier}}

Here,

  • name is the name of the variable;
  • kind indicates how the variable is converted to a string;
  • modifier is an optional conversion parameter.

The Format protocol defines various conversion methods.

template (a (Unicode) string)
A template string.
namespaces, keywords (dictionaries)
Dictionaries containing substitution variables.
write(data)

Writes a string to the SQL stream.

indent()

Sets the indentation level to the current cursor position.

dedent()

Reverts to the previous indentation level.

newline()

Sets the cursor to the current indentation level.

class htsql.tr.dump.Format(kind, value, modifier, state)

Serializes a substitution variable.

This is an auxiliary protocol used by DumpBase.format(). It is called to serialize a substitution variable of the form:

{variable:kind{modifier}}
kind (a string)
The name of the conversion operation. The protocol is polymorphic on this argument.
value (an object)
The value of the variable to be serialized.
modifier (an object or None)
An optional conversion parameter.
state (SerializingState)
The current state of the serializing process.
class htsql.tr.dump.FormatDefault(kind, value, modifier, state)

Dumps a clause node.

This is the default conversion, used when the conversion kind is not specified explicitly:

{clause}

Here, the value of clause is a htsql.tr.frame.Clause instance to serialize.

class htsql.tr.dump.FormatUnion(kind, value, modifier, state)

Dumps a list of clause nodes.

Usage:

{clauses:union}
{clauses:union{ separator }}

Here,

  • the value of the clauses variable is a list of htsql.tr.frame.Clause nodes;
  • separator is a separator between clauses (', ', by default).
class htsql.tr.dump.FormatName(kind, value, modifier, state)

Dumps a SQL identifier.

Usage:

{identifier:name}

The value of identifier is a string, which is serialized as a quoted SQL identifier.

class htsql.tr.dump.FormatLiteral(kind, value, modifier, state)

Dumps a SQL literal.

Usage:

{value:literal}

The value of the value variable is serialized as a quoted SQL literal.

class htsql.tr.dump.FormatNot(kind, value, modifier, state)

Dumps a NOT clause.

Usage:

{polarity:not}

The action depends on the value of the polarity variable:

  • writes nothing when polarity is equal to +1;
  • writes NOT followed by a space when polarity is equal to -1.
class htsql.tr.dump.FormatSwitch(kind, value, modifier, state)

Dumps one of two given clauses.

Usage:

{polarity:switch{P|N}}

The action depends on the value of the polarity variable:

  • writes the P clause when polarity is equal to +1;
  • writes the N clause when polarity is equal to -1.
class htsql.tr.dump.FormatPass(kind, value, modifier, state)

Dumps the given string.

Usage:

{string:pass}

The value of the string variable is written directly to the SQL stream.

class htsql.tr.dump.Dub(clause, state)

Generates a preform alias name for a clause node.

This is an auxiliary adapter used to generate aliases for SELECT and FROM clauses.

clause (htsql.tr.frame.Clause)
A clause node to make an alias for.
state (SerializingState)
The current state of the serializing process.
class htsql.tr.dump.Dump(clause, state)

Translates a clause node to SQL.

This is an interface adapter; see subclasses for implementations.

The Dump adapter has the following signature:

Dump: (Clause, SerializingState) -> writes to SQL stream

The adapter is polymorphic on the Clause argument.

The adapter generates a SQL clause for the given node and writes it to the stream that accumulates a SQL statement.

clause (htsql.tr.frame.Clause)
A clause to serialize.
state (SerializingState)
The current state of the serializing process.
class htsql.tr.dump.DubFrame(clause, state)

Generates a preform alias for a frame node.

class htsql.tr.dump.DumpFrame(frame, state)

Translates a frame node to SQL.

frame (htsql.tr.frame.Frame)
A frame node to serialize.
class htsql.tr.dump.DubPhrase(clause, state)

Generates a preform alias for a phrase node.

class htsql.tr.dump.DumpPhrase(phrase, state)

Translates a phrase node to SQL.

phrase (htsql.tr.frame.Phrase)
A phrase node to serialize.
class htsql.tr.dump.DumpTable(clause, state)

Serializes a table frame.

class htsql.tr.dump.DumpBranch(clause, state)

Serializes a SELECT frame.

class htsql.tr.dump.DumpNested(clause, state)

Serializes a nested SELECT frame.

class htsql.tr.dump.DumpSegment(clause, state)

Serializes a top-level SELECT frame.

class htsql.tr.dump.DumpLeadingAnchor(clause, state)

Serializes the leading subframe in a FROM clause.

class htsql.tr.dump.DumpAnchor(clause, state)

Serializes a successive subframe in a FROM clause.

class htsql.tr.dump.DubColumn(clause, state)

Generates a preform alias for a column reference.

class htsql.tr.dump.DumpColumn(clause, state)

Serializes a reference to a table frame.

class htsql.tr.dump.DubReference(clause, state)

Generates a preform alias for a reference to a nested SELECT.

class htsql.tr.dump.DumpReference(clause, state)

Serializes a reference to a nested subframe.

class htsql.tr.dump.DubEmbedding(clause, state)

Generates a preform alias for a correlated subquery.

class htsql.tr.dump.DumpEmbedding(clause, state)

Serializes an embedded subquery.

class htsql.tr.dump.DumpLiteral(clause, state)

Serializes a literal node.

Serialiation is delegated to the DumpByDomain adapter.

class htsql.tr.dump.DumpNull(clause, state)

Serializes a NULL value.

class htsql.tr.dump.DumpByDomain(phrase, state)

Serializes a literal node.

This is an auxiliary adapter used for serialization of literal nodes. The adapter is polymorphic on the domain of the literal.

phrase (htsql.tr.frame.LiteralPhrase)
A literal node to serialize.
state (SerializingState)
The current state of the serializing process.

Other attributes:

value (depends on the domain or None)
The value of the literal.
domain (htsql.domain.Domain)
The domain of the literal.
class htsql.tr.dump.DumpBoolean(phrase, state)

Serializes a Boolean literal.

class htsql.tr.dump.DumpInteger(phrase, state)

Serializes an integer literal.

class htsql.tr.dump.DumpFloat(phrase, state)

Serializes a float literal.

class htsql.tr.dump.DumpDecimal(phrase, state)

Serializes a decimal literal.

class htsql.tr.dump.DumpString(phrase, state)

Serializes a string literal.

class htsql.tr.dump.DumpEnum(phrase, state)

Serializes a value of an enumerated type.

class htsql.tr.dump.DumpDate(phrase, state)

Serializes a date literal.

class htsql.tr.dump.DumpTime(phrase, state)

Serializes a time literal.

class htsql.tr.dump.DumpDateTime(phrase, state)

Serializes a datetime literal.

class htsql.tr.dump.DumpCast(clause, state)

Serializes a CAST clause.

Serialiation is delegated to the DumpByDomain adapter.

class htsql.tr.dump.DumpToDomain(phrase, state)

Serializes a CAST clause.

This is an auxiliary adapter used for serialization of cast phrase nodes. The adapter is polymorphic on the pair of the origin and the target domains.

phrase (htsql.tr.frame.CastPhrase)
A cast node to serialize.
state (SerializingState)
The current state of the serializing process.

Other attributes:

base (htsql.tr.frame.Phrase)
The operand of the CAST expression.
domain (htsql.domain.Domain)
The target domain.
class htsql.tr.dump.DumpToInteger(phrase, state)

Serializes conversion to an integer value.

Handles conversion from a string and other numeric data types.

class htsql.tr.dump.DumpToFloat(phrase, state)

Serializes conversion to a floating-point number.

Handles conversion from a string and other numeric data types.

class htsql.tr.dump.DumpToDecimal(phrase, state)

Serializes conversion to a decimal number.

Handles conversion from a string and other numeric data types.

class htsql.tr.dump.DumpToString(phrase, state)

Serializes conversion to a string.

Handles conversion from other data types to a string.

class htsql.tr.dump.DumpToDate(phrase, state)

Serializes conversion to a date value.

Handles conversion from a string and a datetime.

class htsql.tr.dump.DumpToTime(phrase, state)

Serializes conversion to a time value.

Handles conversion from a string and a datetime.

class htsql.tr.dump.DumpToDateTime(phrase, state)

Serializes conversion to a datetime value.

Handles conversion from a string.

class htsql.tr.dump.DumpFormula(clause, state)

Serializes a formula node.

Serialiation is delegated to the DumpBySignature adapter.

class htsql.tr.dump.DumpBySignature(phrase, state)

Serializes a formula node.

This is an auxiliary adapter used for serialization of formula nodes. The adapter is polymorphic on the formula signature.

phrase (htsql.tr.frame.FormulaPhrase)
A formula node to serialize.
state (SerializingState)
The current state of the serializing process.

Other attributes:

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (htsql.tr.domain.Domain)
The co-domain of the formula.
arguments (htsql.tr.signature.Bag)
The arguments of the formula.
class htsql.tr.dump.DumpIsEqual(phrase, state)

Serializes an (in)equality (= or !=) operator

class htsql.tr.dump.DumpIsTotallyEqual(phrase, state)

Serializes a total (in)equality (== or !==) operator.

class htsql.tr.dump.DumpIsIn(phrase, state)

Serializes an N-ary equality (={}) operator.

class htsql.tr.dump.DumpAnd(phrase, state)

Serializes a logical “AND” (&) operator.

class htsql.tr.dump.DumpOr(phrase, state)

Serializes a logical “OR” (|) operator.

class htsql.tr.dump.DumpNot(phrase, state)

Serializes a logical “NOT” (!) operator.

class htsql.tr.dump.DumpIsNull(phrase, state)

Serializes an is_null() operator.

class htsql.tr.dump.DumpIfNull(phrase, state)

Serializes an if_null() operator.

class htsql.tr.dump.DumpNullIf(phrase, state)

Serializes a null_if() operator.

class htsql.tr.dump.DumpCompare(phrase, state)

Serializes a comparison operator.

htsql.tr.dump.serialize(clause, state=None)

Translates a clause node to SQL.

clause (htsql.tr.frame.Clause)
The clause to serialize.
state (SerializingState or None)
The serializing state to use. If not set, a new serializing state is instantiated.

htsql.tr.encode

This module implements the encoding process.

class htsql.tr.encode.EncodingState

Encapsulates the (mutable) state of the encoding process.

Currently encoding is a stateless process, but we will likely add extra state in the future. The state is also used to store the cache of binding to flow and binding to code translations.

flush()

Clears the encoding state.

encode(binding)

Encodes the given binding node to a code expression node.

Returns a htsql.tr.flow.Code node (in some cases, a htsql.tr.flow.Expression node).

binding (htsql.tr.binding.Binding)
The binding node to encode.
relate(binding)

Encodes the given binding node to a flow expression node.

Returns a htsql.tr.flow.Flow node.

binding (htsql.tr.binding.Binding)
The binding node to encode.
class htsql.tr.encode.EncodeBase(binding, state)

Applies an encoding adapter to a binding node.

This is a base class for the two encoding adapters: Encode and Relate; it encapsulates methods and attributes shared between these adapters.

The encoding process translates binding nodes to data flows or expressions over data flows.

binding (htsql.tr.binding.Binding)
The binding node to encode.
state (EncodingState)
The current state of the encoding process.
class htsql.tr.encode.Encode(binding, state)

Translates a binding node to a code expression node.

This is an interface adapter; see subclasses for implementations.

The Encode adapter has the following signature:

Encode: (Binding, EncodingState) -> Expression

The adapter is polymorphic on the Binding argument.

This adapter provides non-trivial implementation for binding nodes representing HTSQL functions and operators.

class htsql.tr.encode.Relate(binding, state)

Translates a binding node to a data flow node.

This is an interface adapter; see subclasses for implementations.

The Relate adapter has the following signature:

Relate: (Binding, EncodingState) -> Flow

The adapter is polymorphic on the Binding argument.

The adapter provides non-trivial implementations for scoping and chaining bindings.

class htsql.tr.encode.Convert(binding, state)

Encodes a cast binding to a code node.

This is an auxiliary adapter used to encode htsql.tr.binding.CastBinding nodes. The adapter is polymorphic by the origin and the target domains.

The purpose of the adapter is multifold. The Convert adapter:

binding (htsql.tr.binding.CastBinding)

The binding node to encode.

Note that the adapter is dispatched on the pair (binding.base.domain, binding.domain).

state (EncodingState)
The current state of the encoding process.

Aliases:

base (htsql.tr.binding.Binding)
An alias for binding.base; the operand of the cast expression.
domain (htsql.domain.Domain)
An alias for binding.domain; the target domain.
class htsql.tr.encode.EncodeBySignatureBase(binding, state)

Translates a formula node.

This is a base class for the two encoding adapters: EncodeBySignature and RelateBySignature; it encapsulates methods and attributes shared between these adapters.

The adapter accepts a binding formula node and is polymorphic on the formula signature.

binding (htsql.tr.binding.FormulaBinding)
The formula node to encode.
state (EncodingState)
The current state of the encoding process.

Aliases:

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (htsql.tr.domain.Domain)
The co-domain of the formula.
arguments (htsql.tr.signature.Bag)
The arguments of the formula.
class htsql.tr.encode.EncodeBySignature(binding, state)

Translates a formula binding to a code node.

This is an auxiliary adapter used to encode class:htsql.tr.binding.FormulaBinding nodes. The adapter is polymorphic on the formula signature.

Unless overridden, the adapter encodes the arguments of the formula and generates a new formula code with the same signature.

class htsql.tr.encode.RelateBySignature(binding, state)

Translates a formula binding to a flow node.

This is an auxiliary adapter used to relate class:htsql.tr.binding.FormulaBinding nodes. The adapter is polymorphic on the formula signature.

Unless overridden, the adapter generates an error.

class htsql.tr.encode.RelateWrapping(binding, state)

Translates a wrapper binding to a flow node.

htsql.tr.encode.encode(binding, state=None)

Encodes the given binding to an expression node.

Returns a htsql.tr.flow.Expression instance (in most cases, a htsql.tr.flow.Code instance).

binding (htsql.tr.binding.Binding)
The binding node to encode.
state (EncodingState or None)
The encoding state to use. If not set, a new encoding state is instantiated.
htsql.tr.encode.relate(binding, state=None)

Encodes the given binding to a data flow node.

Returns a htsql.tr.flow.Flow instance.

binding (htsql.tr.binding.Binding)
The binding node to encode.
state (EncodingState or None)
The encoding state to use. If not set, a new encoding state is instantiated.

htsql.tr.error

This module declares exceptions that can be raised by the HTSQL-to-SQL translator.

exception htsql.tr.error.TranslateError(detail, mark)

Represents a translation error.

exception htsql.tr.error.ScanError(detail, mark)

Represents a scanner error.

This exception is raised when the scanner cannot tokenize a query.

exception htsql.tr.error.ParseError(detail, mark)

Represents a parser error.

This exception is raised by the parser when it encounters an unexpected token.

exception htsql.tr.error.BindError(detail, mark)

Represents a binder error.

Raised when the binder is unable to bind a syntax node.

exception htsql.tr.error.EncodeError(detail, mark)

Represents an encoder error.

Raised when the encoder is unable to encode or relate a binding node.

exception htsql.tr.error.CompileError(detail, mark)

Represents a compiler error.

Raised when the compiler is unable to generate a term node.

exception htsql.tr.error.AssembleError(detail, mark)

Represents an assembler error.

Raised when the assembler is unable to generate a frame or a phrase node.

exception htsql.tr.error.SerializeError(detail, mark)

Represents a serializer error.

Raised when the serializer is unable to translate a clause node to SQL.

htsql.tr.flow

This module declares flow and code nodes.

class htsql.tr.flow.Expression(binding, equality_vector=None)

Represents an expression node.

This is an abstract class; most of its subclasses belong to one of the two categories: flow and code nodes (see Flow and Code).

A flow graph is an intermediate phase of the HTSQL translator. It is translated from the binding graph by the encoding process. The flow graph is used to compile the term tree and then assemble the frame structure.

A flow graph reflects the flow structure of the HTSQL query: each expression node represents either a data flow or an expression over a data flow.

Expression nodes support equality by value: that is, two expression nodes are equal if they are of the same type and all their (essential) attributes are equal. Some attributes (e.g. binding) are not considered essential and do not participate in comparison. By-value semantics is respected when expression nodes are used as dictionary keys.

The constructor arguments:

binding (htsql.tr.binding.Binding)
The binding node that gave rise to the expression; should be used only for presentation or error reporting.
equality_vector (an immutable tuple or None)

Encapsulates all essential attributes of a node. Two expression nodes are considered equal if they are of the same type and their equality vectors are equal. If None, the node is compared by identity.

Note that the binding attribute is not essential and should not be a part of the equality vector.

Other attributes:

syntax (htsql.tr.syntax.Syntax)
The syntax node that gave rise to the expression; for debugging purposes only.
mark (htsql.mark.Mark)
The location of the node in the original query; for error reporting.
hash (an integer)
The node hash; if two nodes are considered equal, their hashes must be equal too.
class htsql.tr.flow.QueryExpr(segment, binding)

Represents the whole HTSQL query.

segment (SegmentExpr or None)
The query segment.
class htsql.tr.flow.SegmentExpr(flow, elements, binding)

Represents a segment of an HTSQL query.

flow (Flow)
The output flow of the segment.
elements (a list of Code)
The output columns of the segment.
class htsql.tr.flow.Family

Represents the target class of a flow.

The flow family specifies the type of values produced by a flow. There are three distinct flow families:

  • scalar, which indicates that the flow produces scalar values;
  • table, which indicates that the flow produces records from a database table;
  • quotient, which indicates that the flow produces records from a derived quotient class.

Class attributes:

is_scalar (Boolean)
Set for a scalar family.
is_table (Boolean)
Set for a table family.
is_quotient (Boolean)
Set for a quotient family.
class htsql.tr.flow.ScalarFamily

Represents a scalar flow family.

A scalar flow produces values of a primitive type.

class htsql.tr.flow.TableFamily(table)

Represents a table flow family.

A table flow produces records from a database table.

table (htsql.entity.TableEntity)
The table.
class htsql.tr.flow.QuotientFamily(seed, ground, kernels)

Represents a quotient flow family.

A quotient flow produces records from a derived quotient class.

The quotient class contains records formed from the kernel expressions as they run over the seed flow.

seed (Flow)
The dividend flow.
ground (Flow)
The ground flow of the dividend.
kernels (list of Code)
The kernel expressions of the quotient.
class htsql.tr.flow.Flow(base, family, is_contracting, is_expanding, binding, equality_vector=None)

Represents a flow node.

A data flow is a sequence of homogeneous values. A flow is generated by a series of flow operations applied sequentially to the root flow.

Each flow operation takes an input flow as an argument and produces an output flow as a result. The operation transforms each element from the input row into zero, one, or more elements of the output flow; the generating element is called the origin of the generated elements. Thus, with every element of a flow, we could associate a sequence of origin elements, one per each elementary flow operation that together produce the flow.

Each instance of Flow represents a single flow operation applied to some input flow. The base attribute of the instance represents the input flow while the type of the instance and the other attributes reflect the properies of the operation. The root flow is denoted by an instance of:class:RootFlow, different subclasses of Flow correspond to different types of flow operations.

The type of values produced by a flow is indicated by the family attribute. We distinguish three flow families: scalar, table and quotient. A scalar flow produces values of an elementary data type; a table flow produces records of some table; a quotient flow produces elements of a derived quotient class.

Among others, we consider the following flow operations:

The root flow I
The initial flow that contains one empty record.
A direct product A * T
Given a scalar flow A and a table T, the direct product A * T generates all records of T for each element of A.
A fiber product A . T
Given an input flow A that produces records of some table S and a table T linked to S, for each element of A, the fiber product A . T generates all associated records from T.
Filtering A ? p
Given a flow A and a predicate p defined on A, the filtered flow A ? p consists of all elements of A satisfying condition p.
Ordering A [e,...]
Given a flow A and a list of expressions e,..., the ordered flow A [e,...] consists of elements of A reordered by the values of e,....
Quotient A ^ k
Given a flow A and a kernel expression k defined on A, a quotient A ^ k produces all unique values of the kernel as it runs over A.

Flow operations for which the output flow does not consist of elements of the input flow are called axial. If we take an arbitrary flow A, disassemble it into individual operations, and then reapply only axial operations, we get the new flow A', which we call the inflation of A. Note that elements of A form a subset of elements of A'.

Now we can establish how different flows are related to each other. Formally, for each pair of flows A and B, we define a relation <-> (“converges to”) on elements from A and B, that is, a subset of the Cartesian product A x B, by the following rules:

  1. For any flow A, <-> is the identity relation on A, that is, each element converges only to itself.

    For a flow A and its inflation A', each element from A converges to an equal element from A'.

  2. Suppose A and B are flows such that A is produced from B as a result of some axial flow operation. Then each element from A converges to its origin element from B.

    By transitivity, we could extend <-> on A and any of its ancestor flows, that is, the parent flow of A, the parent of the parent of A and so on.

    In particular, this defines <-> on an arbitrary flow A and the root flow I since I is an ancestor of any flow. By the above definition, any element of A converges to the (only) record of I.

  3. Finally, we are ready to define <-> on an arbitrary pair of flows A and B. First, suppose that A and B share the same inflated flow: A' = B'. Then we could define <-> on A and B transitively via A': a from A converges to b from B if there exists a' from A' such that a <-> a' and a' <-> b.

    In the general case, find the closest ancestors C of A and D of B such that C and D have the same inflated flow: C' = D'. Rules (1) and (2) establish <-> for the pairs A and C, C and C' = D', C' = D' and D, and D and B. We define <-> on A and B transitively: a from A converges to b from B if there exist elements c from C, c' from C' = D', d from D such that a <-> c <-> c' <-> d <-> b.

    Note that it is important that we take among the common inflated ancestors the closest one. Any two flows have a common inflated ancestor: the root flow. If the root flow is, indeed, the closest common inflated ancestor of A and B, then each element of A converges to every element of B.

Now we are ready to introduce several important relations between flows:

A spans B

A flow A spans a flow B if for every element a from A:

card { b from B | a <-> b } <= 1.

Informally, it means that the statement:

SELECT * FROM A

and the statement:

SELECT * FROM A LEFT OUTER JOIN B ON (A <-> B)

produce the same number of rows.

A dominates B

A flow A dominates a flow B if A spans B and for every element b from B:

card { a from A | a <-> b } >= 1.

Informally, it implies that the statement:

SELECT * FROM B INNER JOIN A ON (A <-> B)

and the statement:

SELECT * FROM B LEFT OUTER JOIN A ON (A <-> B)

produce the same number of rows.

A conforms B

A flow A conforms a flow B if A dominates B and B dominates A. Alternatively, we could say A conforms B if the <-> relation establishes a bijection between A and B.

Informally, it means that the statement:

SELECT * FROM A

and the statement:

SELECT * FROM B

produce the same number of rows.

Note that A conforming B is not the same as A being equal to B; even if A conforms B, elements of A and B may be of different types, therefore as sets, they are different.

Now take an arbitrary flow A and its parent flow B. We say:

A contracts B

A flow A contracts its parent B if for any element from B there is no more than one converging element from A.

Typically, it is non-axis flows that contract their bases, although in some cases, an axis flow could do it too.

A expands B

A flow A expands its parent B if for any element from B there is at least one converging element from A.

Note that it is possible that a flow A both contracts and expands its base B, and also that A neither contracts nor expands B. The former means that A conforms B. The latter holds, in particular, for the direct table flow A * T. A * T violates the contraction condition when T contains more than one record and violates the expansion condition when T has no records.

A few words about how elements of a flow are ordered. The default (also called weak) ordering rules are:

  • a table flow T = I * T is sorted by the lexicographic order of the table primary key;
  • a non-axial flow keeps the order of its base;
  • an axial table flow A * T or A . T respects the order its base A; records with the same origin are sorted by the table order.

An alternative sort order could be specified explicitly (also called strong ordering). Whenever strong ordering is specified, it overrides the weak ordering. Thus, elements of an ordered flow A [e] are sorted first by expression e, and then elements which are not differentiated by e are sorted using the weak ordering of A. However, if A already has a strong ordering, it must be respected. Therefore, the general rule for sorting A [e] is:

  • first, sort the flow by the strong ordering of A;
  • then, by e;
  • finally, by the weak ordering of A.

Class attributes:

is_axis (Boolean)
Indicates whether the flow is axial, that is, the elements of the flow do not necessarily coincide with their origins.
is_root (Boolean)
Indicates that the flow is the root flow.

The constructor arguments:

base (Flow or None)
The parent input flow; None for the root flow.
family (Family)
Specifies the type of the elements produced by the flow.
is_contracting (Boolean)
Indicates if the flow contracts its base flow.
is_expanding (Boolean)
Indicates if the flow expands its base flow.

Other attributes:

is_inflated (Boolean)
Indicates if the flow is an inflation, that is, this flow operation and all its ancestors are axial.
unfold()

Produces a list of ancestor flows.

The method returns a list composed of the flow itself, its base, the base of its base and so on.

resembles(other)

Verifies if the flows represent the same operation.

Typically, it means that self and other have the same type and equal attributes, but may have different bases.

inflate()

Produces the inflation of the flow.

If we represent a flow as a series of operations sequentially applied to the scalar flow, the inflation of the flow is obtained by ignoring any non-axial operations and applying axial operations only.

prune(other)

Prunes shared non-axial operations.

Given flows A and B, this function produces a new flow A' such that A is a subset of A' and the convergence of A and B coincides with the convergence of A' and B. This is done by pruning any non-axial operations of A that also occur in B.

spans(other)

Verifies if the flow spans another flow.

conforms(other)

Verifies if the flow conforms another flow.

dominates(other)

Verifies if the flow dominates another flow.

concludes(other)

Verifies if the other flow is a ancestor of the flow.

class htsql.tr.flow.RootFlow(base, binding)

Represents a root scalar flow.

A root flow I contains one record (). Any other flow is generated by applying a sequence of elementary flow operations to I.

base (always None)
The root flow (and only the root flow) has no parent flow.
class htsql.tr.flow.ScalarFlow(base, binding)

Represents a link to the scalar class.

Traversing a link to the scalar class produces an empty record () for each element of the input flow.

class htsql.tr.flow.TableFlow(base, family, is_contracting, is_expanding, binding, equality_vector=None)

Represents a product of an input flow to a table.

A product operation generates a subset of a Cartesian product between the base flow and records of a table. This is an abstract class, see concrete subclasses DirectTableFlow and FiberTableFlow.

table (htsql.entity.TableEntity)
The table.
class htsql.tr.flow.DirectTableFlow(base, table, binding)

Represents a direct product between a scalar flow and a table.

A direct product A * T produces all records of the table T for each element of the input flow A.

base (Flow)
The base flow.
table (htsql.entity.TableEntity)
The table.
class htsql.tr.flow.FiberTableFlow(base, join, binding)

Represents a fiber product between a table flow and a linked table.

Let A be a flow producing records of table S, j be a join condition between tables S and T. A fiber product A .j T (or A . T when the join condition is implied) of the flow A and the table T is a sequence of records of T that for each record of A generates all records of T satisfying the join condition j.

base (Flow)
The base flow.
join (htsql.entity.Join)
The join condition.
class htsql.tr.flow.QuotientFlow(base, seed, kernels, binding, companions=[])

Represents a quotient operation.

A quotient operation takes three arguments: an input flow A, a seed flow S, which should be a descendant of the input flow, and a kernel expression k on the seed flow. For each element of the input flow, the output flow A . (S ^ k) generates unique values of k as it runs over convergent elements of S.

base (Flow)
The base flow.
seed (Flow)
The seed flow of the quotient; must be a descendant of the base flow.
kernels (a list of Code)
Kernel expressions of the quotient.
companions (a list of Code)
An auxiliary hint to the compiler indicating that the term representing the flow needs to export extra aggregate units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.

Other attributes:

ground (Flow)
The closest axial ancestor of seed that is spanned by the base flow.
class htsql.tr.flow.ComplementFlow(base, binding, companions=[])

Represents a complement to a quotient.

A complement takes a quotient as an input flow and generates elements of the quotient seed.

base (Flow)
The base flow.
companions (list of Code)
An auxiliary hint to the compiler indicating that the term representing the flow needs to export extra covering units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.

Other attributes:

seed (Flow)
The seed flow of the quotient.
ground (Flow)
The grond flow of the quotient.
kernels (list of Code)
Kernel expressions of the quotient.
class htsql.tr.flow.MonikerFlow(base, seed, binding, companions=[])

Represents an moniker operation.

A moniker masks an arbitrary sequence of operations as a single axial flow operation.

base (Flow)
The base flow.
seed (Flow)
The seed flow.
companions (list of Code)
An auxiliary hint to the compiler indicating that the term representing the flow must export extra covering units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.

Other attributes:

ground (Flow)
The closest axial ancestor of seed spanned by base.
class htsql.tr.flow.ForkedFlow(base, seed, kernels, binding, companions=[])

Represents a fork expression.

A fork expression associated each element of the input flow with every element of the input flow sharing the same origin and values of the kernel expression.

base (Flow)
The base flow.
seed (Flow)
The flow to fork (typically coincides with the base flow).
kernels (list of Code)
The kernel expressions.
companions (list of Code)
An auxiliary hint to the compiler indicating that the term representing the flow must export extra covering units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.

Other attributes:

ground (Flow)
The closest axial ancestor of the seed flow.
class htsql.tr.flow.LinkedFlow(base, seed, images, binding, companions=[])

Represents a linking operation.

A linking operation generates, for every element of the input flow, convergent elements from the seed flow with the same image value.

base (Flow)
The base flow.
seed (Flow)
The seed flow.
images (list of pairs of Code)
Pairs of expressions forming a fiber join condition.
companions (list of Code)
An auxiliary hint to the compiler indicating that the term representing the flow must export extra covering units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.

Other attributes:

ground (Flow)
The closest axial ancestor of seed spanned by base.
class htsql.tr.flow.FilteredFlow(base, filter, binding)

Represents a filtering operation.

A filtered flow A ? f, where A is the input flow and f is a predicate expression on A, consists of rows of A satisfying the condition f.

base (Flow)
The base flow.
filter (Code)
The predicate expression.
class htsql.tr.flow.OrderedFlow(base, order, limit, offset, binding)

Represents an ordered flow.

An ordered flow A [e,...;p:q] is a flow with explicitly specified strong ordering. It also may extract a slice of the input flow.

base (Flow)
The base flow.
order (a list of pairs (code, direction))

Expressions to sort the flow by.

Here code is a Code instance, direction is either +1 (indicates ascending order) or -1 (indicates descending order).

limit (a non-negative integer or None)
If set, the flow extracts the first limit rows from the base flow (with respect to the flow ordering). The remaining rows are discarded.
offset (a non-negative integer or None)
If set, indicates that when extracting rows from the base flow, the first offset rows should be skipped.
class htsql.tr.flow.Code(domain, units, binding, equality_vector=None)

Represents a code expression.

A code expression is a function on flows. Specifically, it is a functional (possibly of several variables) that maps a flow (or a Cartesian product of several flows) to some scalar domain. Code is an abstract base class for all code expressions; see its subclasses for concrete types of expressions.

Among all code expressions, we distinguish unit expressions: elementary functions on flows. There are several kinds of units: among them are table columns and aggregate functions (see Unit for more detail). A non-unit code could be expressed as a composition of a scalar function and one or several units:

f = f(a,b,...) = F(u(a),v(b),...),

where

  • f is a code expression;
  • F is a scalar function;
  • a, b, ... are elements of flows A, B, ...;
  • u, v, ... are unit expressions on A, B, ....

Note: special forms like COUNT or EXISTS are also expressed as code nodes. Since they are not regular functions, special care must be taken to properly wrap them with appropriate ScalarUnit and/or AggregateUnit instances.

domain (htsql.domain.Domain)
The co-domain of the code expression.
units (a list of Unit)
The unit expressions of which the code is composed.
class htsql.tr.flow.LiteralCode(value, domain, binding)

Represents a literal value.

value (valid type depends on the domain)
The value.
domain (htsql.domain.Domain)
The value type.
class htsql.tr.flow.CastCode(base, domain, binding)

Represents a type conversion operator.

base (Code)
The expression to convert.
domain (htsql.domain.Domain)
The target domain.
class htsql.tr.flow.FormulaCode(signature, domain, binding, **arguments)

Represents a formula code.

A formula code represents a function or an operator call as a code node.

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (Domain)
The co-domain of the formula.
arguments (a dictionary)

The arguments of the formula.

Note that all the arguments become attributes of the node object.

class htsql.tr.flow.Unit(flow, domain, binding, equality_vector=None)

Represents a unit expression.

A unit is an elementary function on a flow. There are several kinds of units; see subclasses ColumnUnit, ScalarUnit, AggregateUnit, and CorrelatedUnit for more detail.

Units are divided into two categories: primitive and compound.

A primitive unit is an intrinsic function of its flow; no additional calculations are required to generate a primitive unit. Currently, the only example of a primitive unit is ColumnUnit.

A compound unit requires calculating some non-intrinsic function on the target flow. Among compound units there are ScalarUnit and AggregateUnit, which correspond respectively to scalar and aggregate functions on a flow.

Note that it is easy to lift a unit code from one flow to another. Specifically, suppose a unit u is defined on a flow A and B is another flow such that B spans A. Then for each row b from B there is no more than one row a from A such that a <-> b. Therefore we could define u on B as follows:

  • u(b) = u(a) if there exists a from A such that a <-> b;
  • u(b) = NULL if there is no rows in A convergent to b.

When a flow B spans the flow A of a unit u, we say that u is singular on B. By the previous argument, u could be lifted to B. Thus any unit is well-defined not only on the flow where it is originally defined, but also on any flow where it is singular.

Attributes:

flow (Flow)
The flow on which the unit is defined.
domain (htsql.domain.Domain)
The unit co-domain.

Class attributes:

is_primitive (Boolean)
If set, indicates that the unit is primitive.
is_compound (Boolean)
If set, indicates that the unit is compound.
singular(flow)

Verifies if the unit is singular (well-defined) on the given flow.

class htsql.tr.flow.PrimitiveUnit(flow, domain, binding, equality_vector=None)

Represents a primitive unit.

A primitive unit is an intrinsic function on a flow.

This is an abstract class; for the (only) concrete subclass, see ColumnUnit.

class htsql.tr.flow.CompoundUnit(code, flow, domain, binding, equality_vector=None)

Represents a compound unit.

A compound unit is some non-intrinsic function on a flow.

This is an abstract class; for concrete subclasses, see ScalarUnit, AggregateUnit, etc.

code (Code)
The expression to evaluate on the unit flow.
class htsql.tr.flow.ColumnUnit(column, flow, binding)

Represents a column unit.

A column unit is a function on a flow that returns a column of the prominent table of the flow.

column (htsql.entity.ColumnEntity)
The column produced by the unit.
flow (Flow)
The unit flow. The flow must be of a table family and the flow table must coincide with the column table.
class htsql.tr.flow.ScalarUnit(code, flow, binding, companions=[])

Represents a scalar unit.

A scalar unit is an expression evaluated in the specified flow.

Recall that any expression has the following form:

F(u(a),v(b),...),

where

  • F is a scalar function;
  • a, b, ... are elements of flows A, B, ...;
  • u, v, ... are unit expressions on A, B, ....

We require that the units of the expression are singular on the given flow. If so, the expression units u, v, ... could be lifted to the given slace (see Unit). The scalar unit is defined as

F(u(x),v(x),...),

where x is an element of the flow where the scalar unit is defined.

code (Code)
The expression to evaluate.
flow (Flow)
The flow on which the unit is defined.
companions (list of Code)
An auxiliary hint to the compiler indicating that the term exporting the unit must also export extra scalar units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.
class htsql.tr.flow.AggregateUnitBase(code, plural_flow, flow, binding)

Represents an aggregate unit.

Aggregate units express functions on sets. Specifically, let A and B be flows such that B spans A, but A does not span B, and let g be a function that takes subsets of B as an argument. Then we could define an aggregate unit u on A as follows:

u(a) = g({b | a <-> b})

Here, for each row a from A, we take the subset of convergent rows from B and apply g to it; the result is the value of u(a).

The flow A is the unit flow, the flow B is called the plural flow of an aggregate unit, and g is called the composite expression of an aggregate unit.

code (Code)
The composite expression of the aggregate unit.
plural_flow (Flow)
The plural flow of the aggregate unit, that is, the flow which subsets form the argument of the composite expression.
flow (Flow)
The flow on which the unit is defined.
class htsql.tr.flow.AggregateUnit(code, plural_flow, flow, binding, companions=[])

Represents a regular aggregate unit.

A regular aggregate unit is expressed in SQL using an aggregate expression with GROUP BY clause.

companions (list of Code)
An auxiliary hint to the compiler indicating that the term exporting the unit must also export extra aggregate units. The value of this attribute has no effect on the semantics of the flow graph and node comparison.
class htsql.tr.flow.CorrelatedUnit(code, plural_flow, flow, binding)

Represents a correlated aggregate unit.

A correlated aggregate unit is expressed in SQL using a correlated subquery.

class htsql.tr.flow.KernelUnit(code, flow, binding)

Represents a value generated by a quotient flow.

A value generated by a quotient is either a part of a kernel expression or a unit from a ground flow.

code (Code)
An expression (calculated against the seed flow of the quotient).
flow (Flow)
The flow of the quotient family on which the unit is defined.
class htsql.tr.flow.CoveringUnit(code, flow, binding)

Represents a value generated by a covering flow.

A covering flow represents another flow expression as a single axial flow operation.

code (Code)
An expression (calculated against the seed flow of the covering flow).
flow (Flow)
The flow on which the unit is defined.

htsql.tr.frame

This module declares frame and phrase nodes.

class htsql.tr.frame.Clause(expression, equality_vector=None)

Represents a SQL clause.

This is an abstract class; its subclasses are divided into two categories: frames (see Frame) and phrases (see Phrase).

A clause tree represents a SQL statement and is the next-to-last structure of the HTSQL translator. A clause tree is translated from the term tree and the code graph by the assembling process. It is then translated to SQL by the serializing process.

The following adapters are associated with the assembling process and generate new clause nodes:

Assemble: (Term, AssemblingState) -> Frame
Evaluate: (Code, AssemblingState) -> Phrase

See htsql.tr.assemble.Assemble and htsql.tr.assemble.Evaluate for more detail.

The following adapter is associated with the serializing process:

Dump: (Clause, DumpingState) -> str

See htsql.tr.dump.Dump for more detail.

Clause nodes support equality by value.

The constructor arguments:

expression (htsql.tr.flow.Expression)
The expression node that gave rise to the clause; for debugging and error reporting only.
equality_vector (an immutable tuple or None)

Encapsulates all essential attributes of a node. Two clauses are equal if and only if they are of the same type and their equality vectors are equal. If None, the clause is compared by identity.

Note that the expression attribute is not essential and should not be a part of the equality vector.

Other attributes:

binding (htsql.tr.binding.Binding)
The binding node that gave rise to the expression; for debugging purposes only.
syntax (htsql.tr.syntax.Syntax)
The syntax node that gave rise to the expression; for debugging purposes only.
mark (htsql.mark.Mark)
The location of the node in the original query; for error reporting.
hash (an integer)
The node hash; if two nodes are considered equal, their hashes must be equal too.
class htsql.tr.frame.Frame(kids, term)

Represents a SQL frame.

A frame is a node in the query tree, that is, one of these:

  • a top level SELECT clause, the root of the tree;
  • a nested SELECT clause, a branch of the tree;
  • a table or a scalar (DUAL) clause, a leaf of the tree.

Frame is an abstract case class, see subclasses for concrete frame types.

Each frame node has a unique (in the context of the whole tree) identifier called the tag. Tags are used to refer to frame nodes indirectly.

As opposed to phrases, frame nodes are always compared by identity.

Class attributes:

is_leaf (Boolean)
Indicates that the frame is terminal (either a table or a scalar).
is_scalar (Boolean)
Indicates that the frame is a scalar frame.
is_table (Boolean)
Indicates that the frame is a table frame.
is_branch (Boolean)
Indicates that the frame is non-terminal (either nested or a segment).
is_nested (Boolean)
Indicates that the frame is a nested branch frame.
is_segment (Boolean)
Indicates that the frame is the segment frame.

Constructor arguments:

kids (a list of Frame)
A list of child frames.
term (htsql.tr.term.Term)
The term node that gave rise to the frame.

Other attributes:

tag (an integer)
A unique identifier of the frame; inherited from the term.
flow (htsql.tr.flow.Flow)
The flow represented by the frame; inherited from the term.
baseline (htsql.tr.flow.Flow)
The baseline flow of the frame; inherited from the term.
class htsql.tr.frame.LeafFrame(term)

Represents a leaf frame.

This is an abstract class; for concrete subclasses, see ScalarFrame and TableFrame.

class htsql.tr.frame.ScalarFrame(term)

Represents a scalar frame.

In SQL, a scalar frame is embodied by a special one-row DUAL table.

class htsql.tr.frame.TableFrame(table, term)

Represents a table frame.

In SQL, table frames are serialized as tables in the FROM list.

table (htsql.entity.TableEntity)
The table represented by the frame.
class htsql.tr.frame.BranchFrame(include, embed, select, where, group, having, order, limit, offset, term)

Represents a branch frame.

This is an abstract class; for concrete subclasses, see NestedFrame and SegmentFrame.

In SQL, a branch frame is serialized as a top level (segment) or a nested SELECT statement.

include (a list of Anchor)
Represents the FROM clause.
embed (a list of NestedFrame)

Correlated subqueries that are used in the frame.

A correlated subquery is a sub-SELECT statement that appears outside the FROM list. The embed list keeps all correlated subqueries that appear in the frame. To refer to a correlated subquery from a phrase, use EmbeddingPhrase.

select (a list of Phrase)
Represents the SELECT clause.
where (Phrase or None)
Represents the WHERE clause.
group (a list of Phrase)
Represents the GROUP BY clause.
having (Phrase or None)
Represents the HAVING clause.
order (a list of pairs (phrase, direction))

Represents the ORDER BY clause.

Here phrase is a Phrase instance, direction is either +1 (indicates ascending order) or -1 (indicates descending order).

limit (a non-negative integer or None)
Represents the LIMIT clause.
offset (a non-negative integer or None)
Represents the OFFSET clause.
class htsql.tr.frame.NestedFrame(include, embed, select, where, group, having, order, limit, offset, term)

Represents a nested SELECT statement.

class htsql.tr.frame.SegmentFrame(include, embed, select, where, group, having, order, limit, offset, term)

Represents a top-level SELECT statement.

class htsql.tr.frame.Anchor(frame, condition, is_left, is_right)

Represents a JOIN clause.

frame (Frame)
The joined frame.
condition (Phrase or None)
The join condition.
is_left (Boolean)
Indicates that the join is LEFT OUTER.
is_right (Boolean)
Indicates that the join is RIGHT OUTER.

Other attributes:

is_inner (Boolean)
Indicates that the join is INNER (that is, not left or right).
is_cross (Boolean)
Indicates that the join is CROSS (that is, inner without any join condition).
class htsql.tr.frame.LeadingAnchor(frame, condition=None, is_left=False, is_right=False)

Represents the leading frame in the FROM list.

frame (Frame)
The leading frame.
condition (None)
The join condition.
is_left (False)
Indicates that the join is LEFT OUTER.
is_right (False)
Indicates that the join is RIGHT OUTER.
class htsql.tr.frame.QueryFrame(segment, term)

Represents the whole HTSQL query.

segment (SegmentFrame or None)
The query segment.
class htsql.tr.frame.Phrase(domain, is_nullable, expression, equality_vector)

Represents a SQL expression.

domain (htsql.domain.Domain)
The co-domain of the expression.
is_nullable (Boolean)
Indicates if the expression may evaluate to NULL.
class htsql.tr.frame.LiteralPhrase(value, domain, expression)

Represents a literal value.

value (valid type depends on the domain)
The value.
domain (htsql.domain.Domain)
The value type.
class htsql.tr.frame.NullPhrase(domain, expression)

Represents a NULL value.

NULL values are commonly generated and checked for, so for convenience, they are extracted in a separate class. Note that it is also valid for a NULL value to be represented as a regular LiteralPhrase instance.

class htsql.tr.frame.TruePhrase(expression)

Represents a TRUE value.

TRUE values are commonly generated and checked for, so for convenience, they are extracted in a separate class. Note that it is also valid for a TRUE value to be represented as a regular LiteralPhrase instance.

class htsql.tr.frame.FalsePhrase(expression)

Represents a FALSE value.

FALSE values are commonly generated and checked for, so for convenience, they are extracted in a separate class. Note that it is also valid for a FALSE value to be represented as a regular LiteralPhrase instance.

class htsql.tr.frame.CastPhrase(base, domain, is_nullable, expression)

Represents the CAST operator.

base (Phrase)
The expression to convert.
domain (htsql.domain.Domain)
The target domain.
class htsql.tr.frame.FormulaPhrase(signature, domain, is_nullable, expression, **arguments)

Represents a formula phrase.

A formula phrase represents a function or an operator call as a phrase node.

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (Domain)
The co-domain of the formula.
arguments (a dictionary)

The arguments of the formula.

Note that all the arguments become attributes of the node object.

class htsql.tr.frame.ExportPhrase(tag, domain, is_nullable, expression, equality_vector)

Represents a value exported from another frame.

This is an abstract class; for concrete subclasses, see ColumnPhrase, ReferencePhrase, and EmbeddingPhrase.

tag (an integer)
The tag of the frame that exports the value.
class htsql.tr.frame.ColumnPhrase(tag, column, is_nullable, expression)

Represents a column exported from a table frame.

tag (an integer)

The tag of the table frame.

The tag must point to an immediate child of the current frame.

class (htsql.entity.ColumnEntity)
The column to export.
class htsql.tr.frame.ReferencePhrase(tag, index, domain, is_nullable, expression)

Represents a value exported from a nested sub-SELECT frame.

tag (an integer)

The tag of the nested frame.

The tag must point to an immediate child of the current frame.

index (an integer)
The position of the exported value in the SELECT clause.
class htsql.tr.frame.EmbeddingPhrase(tag, domain, is_nullable, expression)

Represents an embedding of a correlated subquery.

tag (an integer)

The tag of the nested frame.

The tag must point to one of the subframes contained in the embed list of the current frame.

htsql.tr.lookup

This module implements name resolution adapters.

class htsql.tr.lookup.Probe

Represents a lookup request.

class htsql.tr.lookup.AttributeProbe(name, arity)

Represents a request for an attribute.

The result of this probe is a htsql.tr.binding.Recipe instance.

name (a Unicode string)
The attribute name.
arity (an integer or None)
The number of parameters.

Other attributes:

key (a string)
The normal form of the name.
class htsql.tr.lookup.ReferenceProbe(name)

Represents a request for a reference.

The result of this probe is a htsql.tr.binding.Recipe instance.

name (a Unicode string)
The reference name.

Other attributes:

key (a string)
The normal form of the name.
class htsql.tr.lookup.ComplementProbe

Represents a request for a complement link.

The result of this probe is a htsql.tr.binding.Recipe instance.

class htsql.tr.lookup.ExpansionProbe(is_soft=True, is_hard=True)

Represents expansion requests.

The result of this probe is a list of pairs (recipe, syntax), where recipe is an instance of htsql.tr.binding.Recipe and syntax is an instance of htsql.tr.syntax.Syntax.

is_soft (Boolean)
If set, expand selections.
is_hard (Boolean)
If set, expand classes.
class htsql.tr.lookup.GuessNameProbe

Represents a request for an attribute name.

The result of the probe is a string value – an appropriate name of a binding.

class htsql.tr.lookup.GuessTitleProbe

Represents a request for a title.

The result of this probe is a list of headings.

class htsql.tr.lookup.DirectionProbe

Represents a request for a direction modifier.

The result of this probe is +1 or -1 — the direction indicator.

class htsql.tr.lookup.Lookup(binding, probe)

Extracts information from a binding node.

This is an interface adapter, see subclasses for implementations.

The Lookup adapter has the following signature:

Lookup: (Binding, Probe) -> ...

The adapter is polymorphic on both arguments. The type of the output value depends on the type of the Probe argument. None is returned when the request cannot be satisfied.

binding (htsql.tr.binding.Binding)
The binding node.
probe (Probe)
The lookup request.
htsql.tr.lookup.lookup(binding, probe)

Applies a lookup probe to a binding node.

The type of a returned value depends on the type of probe. The value of None indicates the lookup request failed.

binding (htsql.tr.binding.Binding)
A binding node.
probe (Probe)
A lookup probe.
htsql.tr.lookup.lookup_attribute(binding, name, arity=None)

Finds an attribute in the scope of the given binding.

Returns an instance of htsql.tr.binding.Recipe or None if an attribute is not found.

binding (htsql.tr.binding.Binding)
A binding node.
name (a Unicode string)
An attribute name.
arity (an integer or None)
The number of arguments for a parameterized attribute; None for an attribute without parameters.
htsql.tr.lookup.lookup_reference(binding, name)

Finds a reference in the scope of the given binding.

Returns an instance of htsql.tr.binding.Recipe or None if a reference is not found.

binding (htsql.tr.binding.Binding)
A binding node.
name (a Unicode string)
A reference name.
htsql.tr.lookup.lookup_complement(binding)

Extracts a complement link from the scope of the given binding.

Returns an instance of htsql.tr.binding.Recipe or None if a complement link is not found.

binding (htsql.tr.binding.Binding)
A binding node.
htsql.tr.lookup.expand(binding, is_soft=True, is_hard=True)

Extracts public attributes from the given binding.

Returns a list of pairs (syntax, recipe), where recipe is an instance of htsql.tr.binding.Recipe and syntax is an instance of htsql.tr.syntax.Syntax. The function returns None if the scope does not support public attributes.

is_soft (Boolean)
If set, the function expands selector expressions.
is_hard (Boolean)
If set, the function expands classes.
htsql.tr.lookup.guess_name(binding)

Extracts an attribute name from the given binding.

Returns a string value; None if the node is not associated with any attribute.

htsql.tr.lookup.guess_title(binding)

Extracts a heading from the given binding.

Returns a list of string values: the header associated with the binding node.

htsql.tr.lookup.direct(binding)

Extracts a direction indicator.

Returns +1 or -1 to indicate ascending or descending order respectively; None if the node does not have a direction indicator.

htsql.tr.parse

This module implements the HTSQL parser.

class htsql.tr.parse.Parser(input)

Implements an HTSQL parser.

A parser takes a stream of tokens from the HTSQL scanner and produces a node of a syntax tree.

This is an abstract class; see subclasses of Parser for implementations of various parts of the HTSQL grammar.

input (a string)
The input HTSQL expression.
parse()

Parses the input expression; returns the corresponding syntax node.

classmethod process(tokens)

Takes a stream of tokens; returns a syntax node.

This function does not have to exhaust the token stream.

The << operator could be used as a synonym for process(); the following expressions are equivalent:

Parser << tokens
Parser.process(tokens)
tokens (htsql.tr.scan.TokenStream)
The stream of tokens to parse.
class htsql.tr.parse.QueryParser(input)

Parses an HTSQL query.

Here is the grammar of HTSQL:

input           ::= segment END

segment         ::= '/' ( top command* )?
command         ::= '/' ':' identifier ( '/' top? | call | flow )?

top             ::= flow ( direction | mapping )*
direction       ::= '+' | '-'
mapping         ::= ':' identifier ( flow | call )?

flow            ::= disjunction ( sieve | quotient | selection )*
sieve           ::= '?' disjunction
quotient        ::= '^' disjunction
selection       ::= selector ( '.' atom )*

disjunction     ::= conjunction ( '|' conjunction )*
conjunction     ::= negation ( '&' negation )*
negation        ::= '!' negation | comparison

comparison      ::= expression ( ( '~' | '!~' |
                                   '<=' | '<' | '>=' |  '>' |
                                   '==' | '=' | '!==' | '!=' )
                                 expression )?

expression      ::= term ( ( '+' | '-' ) term )*
term            ::= factor ( ( '*' | '/' ) factor )*
factor          ::= ( '+' | '-' ) factor | pointer

pointer         ::= specifier ( link | assignment )?
link            ::= '->' flow
assignment      ::= ':=' top

specifier       ::= atom ( '.' atom )*
atom            ::= '@' atom | '*' index? | '^' | selector | group |
                    identifier call? | reference | literal
index           ::= NUMBER | '(' NUMBER ')'

group           ::= '(' top ')'
call            ::= '(' arguments? ')'
selector        ::= '{' arguments? '}'
arguments       ::= argument ( ',' argument )* ','?
argument        ::= segment | top
reference       ::= '$' identifier

identifier      ::= NAME
literal         ::= STRING | NUMBER

Note that this grammar is almost LL(1); one notable exception is the postfix + and - operators.

class htsql.tr.parse.SegmentParser(input)

Parses a segment production.

class htsql.tr.parse.TopParser(input)

Parses a top production.

class htsql.tr.parse.FlowParser(input)

Parses a flow production.

class htsql.tr.parse.DisjunctionParser(input)

Parses a disjunction production.

class htsql.tr.parse.ConjunctionParser(input)

Parses a conjunction production.

class htsql.tr.parse.NegationParser(input)

Parses a negation production.

class htsql.tr.parse.ComparisonParser(input)

Parses a comparison production.

class htsql.tr.parse.ExpressionParser(input)

Parses an expression production.

class htsql.tr.parse.TermParser(input)

Parses a term production.

class htsql.tr.parse.FactorParser(input)

Parses a pointer production.

class htsql.tr.parse.PointerParser(input)

Parses a pointer production.

class htsql.tr.parse.SpecifierParser(input)

Parses a specifier production.

class htsql.tr.parse.AtomParser(input)

Parses an atom production.

class htsql.tr.parse.GroupParser(input)

Parses a group production.

class htsql.tr.parse.SelectorParser(input)

Parses a selector production.

class htsql.tr.parse.IdentifierParser(input)

Parses an identifier production.

htsql.tr.parse.parse(input, Parser=<class 'htsql.tr.parse.QueryParser'>)

Parses the input HTSQL query; returns the corresponding syntax node.

In case of syntax errors, may raise htsql.tr.error.ScanError or htsql.tr.error.ParseError.

input (a string)
An HTSQL query or an HTSQL expression.
Parser (a subclass of Parser)
The parser to use for parsing the input expression. By default, input is treated as a complete HTSQL query.

htsql.tr.plan

This module declares a SQL execution plan.

class htsql.tr.plan.Plan(sql, frame)

Represents a SQL execution plan.

sql (a Unicode string or None)
The SQL statement to execute.
frame (htsql.tr.frame.QueryFrame)
The query frame corresponding to the plan.

htsql.tr.reduce

This module implements the reducing process.

class htsql.tr.reduce.ReducingState

Encapsulates the state of the reducing and collapsing processes.

State attributes:

substitutes (a mapping tag -> list of phrases)
A mapping containing the SELECT clause of collapsed frames.
flush()

Clears the state.

reduce(clause)

Reduces (simplifies) a SQL clause.

Returns an equivalent (possibly the same) clause.

clause (htsql.tr.frame.Clause)
The clause to simplify.
collapse(frame)

Collapses a frame.

Returns an equivalent (possibly the same) frame.

Note that the generated frame may contain some clauses that refer to subframes which no longer exist. To fix broken references, apply reduce() to the returned frame.

frame (htsql.tr.frame.Frame)
The frame to collapse.
class htsql.tr.reduce.Reduce(clause, state)

Reduces (simplifies) a SQL clause.

This is an interface adapter; see subclasses for implementations.

The Reduce adapter has the following signature:

Reduce: (Clause, ReducingState) -> Clause

The adapter is polymorphic on the Claim argument.

clause (htsql.tr.frame.Clause)
The clause node.
state (ReducingState)
The current state of the reducing process.
class htsql.tr.reduce.ReduceFrame(frame, state)

Reduces a SQL frame.

The adapter collapses the subframes of the frame node and simplifies its clauses. This is an abstract adapter; see subclasses for concrete implementations.

frame (htsql.tr.frame.Frame)
The frame node.
state (ReducingState)
The current state of the reducing process.
class htsql.tr.reduce.ReduceScalar(frame, state)

Reduces a scalar frame.

class htsql.tr.reduce.ReduceBranch(frame, state)

Reduces a top-level or a nested SELECT statement.

class htsql.tr.reduce.Collapse(frame, state)

Collapses nested subframes of the given frame.

Returns an equivalent (possibly the same) frame.

This is an auxiliary adapter used for flattening the frame structure. Using this adapter may remove some frames from the frame tree and thus invalidate any references to these frames. Apply the Reduce adapter to fix the references.

frame (htsql.tr.frame.Frame)
The frame node.
state (ReducingState)
The current state of the reducing process.
class htsql.tr.reduce.CollapseBranch(frame, state)

Collapses a branch frame.

class htsql.tr.reduce.ReduceAnchor(clause, state)

Reduces a JOIN clause.

class htsql.tr.reduce.ReduceQuery(clause, state)

Reduces a top-level query frame.

class htsql.tr.reduce.ReducePhrase(phrase, state)

Reduces a SQL phrase.

class htsql.tr.reduce.ReduceLiteral(clause, state)

Reduces a literal phrase.

class htsql.tr.reduce.ReduceCast(clause, state)

Reduces a CAST operator.

class htsql.tr.reduce.ReduceFormula(clause, state)

Reduces a formula node.

Reducing a formula is specific to the formula signature and is implemented by the ReduceBySignature adapter.

class htsql.tr.reduce.ReduceBySignature(phrase, state)

Reduces a formula node.

This is an auxiliary adapter used to reduce htsql.tr.frame.FormulaPhrase nodes. The adapter is polymorphic on the formula signature.

Unless overridden, the adapter reduces the arguments of the formula and generates a new formula with the same signature.

phrase (htsql.tr.frame.FormulaPhrase)
The formula node to reduce.
state (ReducingState)
The current state of the reducing process.

Aliases:

signature (htsql.tr.signature.Signature)
The signature of the formula.
domain (htsql.tr.domain.Domain)
The co-domain of the formula.
arguments (htsql.tr.signature.Bag)
The arguments of the formula.
is_nullable (Boolean)
Indicates that the formula may produce a NULL value.
class htsql.tr.reduce.ReduceIsEqual(phrase, state)

Reduces an (in)equality operator.

class htsql.tr.reduce.ReduceIsTotallyEqual(phrase, state)

Reduces a total (in)equality operator.

class htsql.tr.reduce.ReduceIsIn(phrase, state)

Reduces the IN and NOT IN clauses.

class htsql.tr.reduce.ReduceIsNull(phrase, state)

Reduces the IS NULL and IS NOT NULL clauses.

class htsql.tr.reduce.ReduceIfNull(phrase, state)

Reduces the IFNULL clause.

class htsql.tr.reduce.ReduceNullIf(phrase, state)

Reduces the NULLIF clause.

class htsql.tr.reduce.ReduceAnd(phrase, state)

Reduces “AND” (&) operator.

class htsql.tr.reduce.ReduceOr(phrase, state)

Reduces “OR” (|) operator.

class htsql.tr.reduce.ReduceNot(phrase, state)

Reduces a “NOT” (!) operator.

class htsql.tr.reduce.ReduceExport(clause, state)

Reduces an export phrase.

class htsql.tr.reduce.ReduceReference(clause, state)

Reduce a reference phrase.

htsql.tr.reduce.reduce(clause, state=None)

Reduces (simplifies) a SQL clause.

Returns an equivalent (possibly the same) clause.

clause (htsql.tr.frame.Clause)
The clause to simplify.
state (ReducingState or None)
The reducing state to use. If not set, a new reducing state is instantiated.

htsql.tr.rewrite

This module implements the rewriting process.

class htsql.tr.rewrite.RewritingState

Encapsulates the state of the rewriting process.

State attributes:

root (htsql.tr.flow.RootFlow)
The root data flow.
mask (htsql.tr.flow.Flow)
The dominant flow; used to prune dependent flows on the unmasking phase.
collection (list of htsql.tr.flow.Unit)
A list of units accumulated on the collecting phase.
set_root(flow)

Set the root data flow.

This function initializes the rewriting state.

root (htsql.tr.flow.RootFlow)
The root flow.
flush()

Clears the state.

spawn()

Creates an empty copy of the state.

push_mask(mask)

Sets a new mask flow.

mask (htsql.tr.flow.Flow)
A new mask flow.
pop_mask()

Restores the previous mask flow.

memorize(expression, replacement)

Memorizes a replacement node for the given expression node.

expression (htsql.tr.flow.Expression)
The expression node to replace.
replacement (htsql.tr.flow.Expression)
The replacement.
rewrite(expression)

Rewrites the given expression node.

Returns an expression node semantically equivalent to the given node, but optimized for compilation. May return the same node.

expression (htsql.tr.flow.Expression)
The expression to rewrite.
unmask(expression, mask=None)

Unmasks the given expression node.

Unmasking prunes non-axial flow operations that are already enforced by the mask flow.

expression (htsql.tr.flow.Expression)
The expression to unmask.
mask (htsql.tr.flow.Flow or None)
If set, specifies the mask to use; otherwise, the current mask is to be used.
collect(expression)

Collects scalar and aggregate units from the given expression.

The collected units are stored in the state attribute collection.

expression (htsql.tr.flow.Expression)
The expression to collect units from.
recombine()

Recombines scalar and aggregate units.

This process adds compilation hints to facilitate merging similar scalar and aggregate units into shared SQL frames.

Updated units are stored in the replace cache.

replace(expression)

Replaces the given expression with a recombined clone.

Returns a new expression node with scalar and aggregate units recombined.

expression (htsql.tr.flow.Expression)
The expression to replace.
class htsql.tr.rewrite.Recombine(state)

Recombines scalar and aggregate units.

This utility adds compilation hints to collected scalar and aggregate units that help the compiler to use shared frames for similar units.

state (RewritingState)
The current state of the rewriting process.
class htsql.tr.rewrite.RewriteBase(expression, state)

Applies the rewriting process to the given node.

This is a base class for all rewriting adapters, it encapsulates common attributes and methods shared by all its subclasses.

Most rewriting adapters have the following signature:

Rewrite: (Expression, RewritingState) -> Expression

The adapters are polymorphic on the first argument.

expression (htsql.tr.flow.Expression)
The expression node to rewrite.
state (RewritingState)
The current state of rewriting process.
class htsql.tr.rewrite.Rewrite(expression, state)

Rewrites the given expression node.

Returns an expression node semantically equivalent to the given node, but optimized for compilation. May return the same node.

class htsql.tr.rewrite.Unmask(expression, state)

Unmasks an expression node.

Unmasking prunes non-axial flow nodes that are already enforced by the current mask flow.

class htsql.tr.rewrite.Collect(expression, state)

Collects scalar and aggregate units in the given expression node.

class htsql.tr.rewrite.Replace(expression, state)

Replaces the given expression with a recombined copy.

class htsql.tr.rewrite.RewriteBySignature(code, state)

Rewrites a formula node.

This is an auxiliary interface used by Rewrite adapter. It is polymorphic on the signature of the formula.

code (htsql.tr.flow.FormulaCode)
The formula node to rewrite.
state (RewritingState)
The current state of rewrite process.
htsql.tr.rewrite.rewrite(expression, state=None)

Rewrites the given expression node.

Returns a clone of the given node optimized for compilation.

expression (htsql.tr.flow.Expression)
The expression node to rewrite.
state (RewritingState or None)
The rewriting state to use. If not set, a new rewriting state is created.

htsql.tr.scan

This module implements the HTSQL scanner.

class htsql.tr.scan.TokenStream(tokens)

A sequence of tokens.

TokenStream wraps a list of tokens with a convenient interface for consumption and look-ahead.

tokens (a list of htsql.tr.token.Token objects)
A list of tokens.
peek(token_class=None, values=None, ahead=0, do_pop=False, do_force=False)

Returns the active token.

If the parameter ahead is non-zero, the method will return the next ahead token after the active one.

When token_class is set, the method checks if the token is an instance of the given class. When values is set, the method checks if the token value belongs to the given list of values. If any of the checks fail, the method either raises htsql.tr.error.ParseError or returns None depending on the value of the do_force parameter.

This method advances the active pointer to the next token if do_pop is enabled.

token_class (a subclass of htsql.tr.token.Token or None)
If not None, the method checks that the returned token is an instance of token_class.
values (a list of Unicode strings or None)
If not None, the method checks that the value of the returned token belongs to the list.
ahead (an integer)
The position of the returned token relative to the active one.
do_pop (Boolean)
If set, the method will advance the active pointer.
do_force (Boolean)
This flag affects the method behavior when any of the token checks fail. If set, the method will raise htsql.tr.error.ParseError; otherwise it will return None.
pop(token_class=None, values=None)

Returns the active token and advances the pointer to the next token.

When token_class is set, the method checks if the token is an instance of the given class. When values is set, the method checks if the token value belongs to the given list of values. If any of the checks fail, the method raises htsql.tr.error.ParseError.

token_class (a subclass of htsql.tr.token.Token or None)
If not None, the method checks that the active token is an instance of token_class.
values (a list of strings or None)
If not None, the method checks that the value of the active token belongs to the list.
class htsql.tr.scan.Scanner(input)

Implements the HTSQL scanner.

The scanner tokenizes the input query and produces a stream of tokens.

The first step of scanning is decoding %-escape sequences. Then the scanner splits the input query to a list of tokens. The following token types are emitted:

NAME
Represents an HTSQL identifier: a sequence of alphanumeric characters that does not start with a digit. Alphanumeric characters include characters a-z, A-Z, 0-9, _, and those Unicode characters that are classified as alphanumeric.
NUMBER
Represents a number literal: integer, float and scientific notations are recognized.
STRING
Represents a string literal enclosed in single quotes; any single quote character should be doubled.
SYMBOL

Represents a valid symbol in HTSQL grammar; one of the following symbols:

comparison operators
=, !=, ==, !==, ~, !~, <, <=, >, >=.
logical operators
!, &, |, ?.
arithmetic operators
+, -, *, /, ^.
assignment operator
:=.
punctuation
(, ), [, ], {, }, ., ,, ->, /, :, $, @.

There are also two special token types:

WHITESPACE
Represents a whitespace character, one of: space, tab, LF, CR, FF, VT, and those Unicode characters that are classified as space. The whitespace token are immediately discarded by the scanner and never emitted.
END
Indicates the end of the query; it is always the last token emitted.

The Scanner constructor takes the following argument:

input
An HTSQL query.
scan()

Tokenizes the query; returns a TokenStream instance.

In case of syntax errors, raises htsql.tr.error.ScanError.

htsql.tr.scan.scan(input)

Tokenizes the input HTSQL query or expression.

Returns a stream of tokens (a TokenStream instance).

In case of syntax errors, raises htsql.tr.error.ScanError.

htsql.tr.signature

This module defines formula nodes and formula signatures.

class htsql.tr.signature.Slot(name, is_mandatory=True, is_singular=True)

Represents a formula slot.

A slot is a parameter of a formula. A slot is to be filled with an argument value when a formula node is instantiated.

name (a string)
The name of the argument.
is_mandatory (Boolean)
Indicates that the slot requires at least one value.
is_singular (Boolean)
Indicates that the slot accepts no more than one value.
class htsql.tr.signature.Signature(equality_vector=())

Represents a formula signature.

A signature identifies the type of a formula. In particular, a signature describes all slots of the formula.

Class attributes:

slots (a list of Slot)
The formula slots.

Constructor arguments:

equality_vector (an immutable tuple)

Encapsulates all essential attributes of a signature.

Two signatures are considered equal if they are of the same type and their equality vectors coincide.

class htsql.tr.signature.Bag(**arguments)

Encapsulates formula arguments.

arguments (a dictionary)

Maps slot names to argument values.

Depending on the slot type, a value could be one of: - a node or None for singular slots; - a list of nodes for plural slots.

A missing argument is indicated by None for a singular slot or by an empty list for a plural slot. Missing arguments are not allowed for mandatory slots.

Bag provides a mapping interface to arguments.

admits(kind, signature)

Verifies that the arguments match the given signature.

Returns True if the arguments match the given signature, False otherwise.

kind (a type)
The expected type of value nodes.
signature (Signature)
The expected signature of the arguments.
cells()

Returns a list of all subnodes.

This function extracts all (singular) nodes from the arguments.

impress(owner)

Adds the arguments as attributes to the given object.

owner (a node object)
An object to update.
map(method)

Applies the given function to all subnodes.

Returns a new Bag instance of the same shape composed from the results of the method application to every value node.

method (a callable)
A function to apply.
freeze()

Returns an immutable container with all the argument values.

This function is useful for constructing an equality vector of a formula node.

class htsql.tr.signature.Formula(signature, arguments, *args, **kwds)

Represents a formula node.

This is a mixin class; it is mixed with htsql.tr.binding.Binding, htsql.tr.code.Code and htsql.tr.frame.Phrase to produce respective formula node types.

signature (Signature)
The formula signature.
arguments (Bag)
The formula arguments; must be compatible with the signature.

The rest of the arguments are passed to the next base class constructor unchanged.

htsql.tr.signature.isformula(formula, signatures)

Checks if a node is a formula with the given signature.

The function returns True if the given node is a formula and its signature is a subclass of the given signature class; False otherwise.

formula (a node, possibly a Formula node)
A node to check.
signatures (a subclass or a tuple of subclasses of Signature)
The expected formula signature(s).
class htsql.tr.signature.NullarySig(equality_vector=())

Represents a signature with no slots.

class htsql.tr.signature.UnarySig(equality_vector=())

Represents a signature with one singular slot.

class htsql.tr.signature.BinarySig(equality_vector=())

Represents a signature with two singular slots.

class htsql.tr.signature.NArySig(equality_vector=())

Represents a signature with one singular slot and one plural slot.

class htsql.tr.signature.ConnectiveSig(equality_vector=())

Represents a signature with one plural slot.

class htsql.tr.signature.PolarSig(polarity)

Denotes a formula with two forms: positive and negative.

polarity (+1 or -1)
Indicates the form of the formula: +1 for positive, -1 for negative.
reverse()

Returns the signature with the opposite polarity.

class htsql.tr.signature.IsEqualSig(polarity)

Denotes an equality (=) and an inequality (!=) operator.

class htsql.tr.signature.IsTotallyEqualSig(polarity)

Denotes a total equality (== and !==) operator.

class htsql.tr.signature.IsInSig(polarity)

Denotes an N-ary equality (={} and !={}) operator.

class htsql.tr.signature.IsNullSig(polarity)

Denotes an is_null() operator.

class htsql.tr.signature.IfNullSig(equality_vector=())

Denotes an if_null() operator.

class htsql.tr.signature.NullIfSig(equality_vector=())

Denotes a null_if() operator.

class htsql.tr.signature.CompareSig(relation)

Denotes a comparison operator.

relation (one of: '<', '<=', '>', '>=')
Indicates the comparison relation.
class htsql.tr.signature.AndSig(equality_vector=())

Denotes a Boolean “AND” (&) operator.

class htsql.tr.signature.OrSig(equality_vector=())

Denotes a Boolean “OR” (|) operator.

class htsql.tr.signature.NotSig(equality_vector=())

Denotes a Boolean “NOT” (!) operator.

htsql.tr.stitch

This module implements stitching utilities over flow nodes.

class htsql.tr.stitch.Arrange(flow, with_strong=True, with_weak=True)

Produces the ordering of the given flow.

Returns a list of pairs (code, direction), where code is an instance of htsql.tr.flow.Code and direction is +1 or -1. This list uniquely identifies sorting order of the flow elements.

This is an interface adapter with a signature:

Arrange: (Flow, bool, bool) -> [(Code, int), ...]

The adapter is polymorphic on the first argument.

flow (htsql.tr.flow.Flow)
The flow to order.
with_strong (Boolean)
If set, include explicit flow ordering.
with_weak (Boolean)
If set, include implicit flow ordering.
class htsql.tr.stitch.Spread(flow)

Produces native units of the given flow.

This is an interface adapter with a singlature:

Spread: Flow -> (Unit, ...)

Native units of the flow are units which are exported by any term representing the flow. Note that together with native units generated by this adapter, a flow term should also export same units reparented against an inflated flow.

flow (htsql.tr.flow.Flow)
The flow node to spread.
class htsql.tr.stitch.Sew(flow)

Generates joints connecting two parallel flows.

This is an interface adapter with a singlature:

Sew: Flow -> (Joint, ...)

The joints produced by the Sew adapter could be used to attach together two term nodes represending the same flow node.

Units in the joints always belong to an inflated flow.

flow (htsql.tr.flow.Flow)
The flow node to sew.
class htsql.tr.stitch.Tie(flow)

Generates joints connecting the given flow to its parent.

This is an interface adapter with a singlature:

Tie: Flow -> (Joint, ...)

The joints produced by the Tie adapter are used to attach a term node representing the flow to a term node representing the origin flow.

Units in the joints always belong to an inflated flow.

flow (htsql.tr.flow.Flow)
The flow node to sew.
htsql.tr.stitch.arrange(flow, with_strong=True, with_weak=True)

Returns the ordering of the given flow.

flow (htsql.tr.flow.Flow)
The flow to order.
with_strong (Boolean)
If set, include explicit flow ordering.
with_weak (Boolean)
If set, include implicit flow ordering.
htsql.tr.stitch.spread(flow)

Returns native units of the given flow.

Na

htsql.tr.syntax

This module defines syntax nodes for the HTSQL grammar.

class htsql.tr.syntax.Syntax(mark, equality_vector)

Represents a syntax node.

The syntax tree expresses the structure of the input HTSQL query, with each node corresponding to some rule in the HTSQL grammar.

mark (htsql.mark.Mark)
The location of the node in the original query.
escape_replace(s, m)

%%%02X

class htsql.tr.syntax.QuerySyntax(segment, mark)

Represents an HTSQL query.

segment (SegmentSyntax)
The top-level segment.
class htsql.tr.syntax.SegmentSyntax(branch, mark)

Represents a segment expression.

branch (Syntax or None)
An expression.
class htsql.tr.syntax.SelectorSyntax(lbranch, rbranches, mark)

Represents a selector expression.

A selector is a comma-separated list of expression enclosed in curly brakets, with an optional selector base:

{<rbranch>, ...}
<lbranch>{<rbranch>, ...}
lbranch (Syntax or None)
The selector base.
rbranches (a list of Syntax)
Selector elements.
class htsql.tr.syntax.ApplicationSyntax(name, arguments, mark, equality_vector)

Represents a function or an operator call.

This is an abstract class with three concrete subclasses corresponding to function calls, function calls in infix form and operators.

name (a Unicode string)
The name of the function or the operator.
arguments (a list of Syntax)
The list of arguments.
class htsql.tr.syntax.FunctionSyntax(identifier, branches, mark)

Represents a function call.

A function call starts with the function name followed by the list of arguments enclosed in parentheses:

<identifier>(<branch>, ...)
identifier (IdentifierSyntax)
The function name.
branches (a list of Syntax)
The list of arguments.
class htsql.tr.syntax.MappingSyntax(identifier, lbranch, rbranches, mark)

Represents a function call in infix or postfix form.

This expression has one of the forms:

<lbranch> :<identifier>
<lbranch> :<identifier> <rbranch>
<lbranch> :<identifier> (<rbranch>, ...)

and is equivalent to a regular function call:

<identifier>(<lbranch>, <rbranch>, ...)
identifier (IdentifierSyntax)
The function name.
lbranch (Syntax)
The left operand.
rbranches (a list of Syntax)
The right operands.
class htsql.tr.syntax.OperatorSyntax(symbol, lbranch, rbranch, mark)

Represents an operator expression.

An operator expression has one of the forms:

<lbranch> <symbol> <rbranch>
          <symbol> <rbranch>
<lbranch> <symbol>

The operator name is composed from the symbol:

  • <symbol> for infix binary operators;
  • <symbol>_ for prefix unary operators;
  • _ for postfix unary operators.

Some operators (those with non-standard precedence) are separated into subclasses of OperatorSyntax.

symbol (a Unicode string)
The operator symbol.
lbranch (Syntax or None)
The left operand.
rbranch (Syntax or None)
The right operand.
class htsql.tr.syntax.QuotientSyntax(lbranch, rbranch, mark)

Represents a quotient operator.

<lbranch> ^ <rbranch>
class htsql.tr.syntax.SieveSyntax(lbranch, rbranch, mark)

Represents a sieve operator.

<lbranch> ? <rbranch>
class htsql.tr.syntax.LinkSyntax(lbranch, rbranch, mark)

Represents a linking operator.

<lbranch> -> <rbranch>
class htsql.tr.syntax.HomeSyntax(rbranch, mark)

Represents a home indicator.

@ <rbranch>
class htsql.tr.syntax.AssignmentSyntax(lbranch, rbranch, mark)

Represents an assignment operator.

<lbranch> := <rbranch>
class htsql.tr.syntax.SpecifierSyntax(lbranch, rbranch, mark)

Represents a specifier expression.

<lbranch> . <rbranch>
class htsql.tr.syntax.GroupSyntax(branch, mark)

Represents an expression in parentheses.

The parentheses are kept in the syntax tree to make sure the serialization from the syntax tree to HTSQL obeys the grammar.

branch (Syntax)
The branch.
class htsql.tr.syntax.IdentifierSyntax(value, mark)

Represents an identifier.

value (a Unicode string)
The identifier value.
class htsql.tr.syntax.WildcardSyntax(index, mark)

Represents a wildcard expression.

*
* <index>
index (NumberSyntax or None)
The index in a wildcard expression.
class htsql.tr.syntax.ComplementSyntax(mark)

Represents a complement expression.

^
class htsql.tr.syntax.ReferenceSyntax(identifier, mark)

Represents a reference.

A reference is an identifier preceded by symbol $:

$ <identifier>
identifier (IdentifierSyntax)
The name of the reference.
class htsql.tr.syntax.LiteralSyntax(value, mark)

Represents a literal expression.

This is an abstract class with subclasses StringSyntax and NumberSyntax.

value (a Unicode string)
The value.
class htsql.tr.syntax.StringSyntax(value, mark)

Represents a string literal.

class htsql.tr.syntax.NumberSyntax(value, mark)

Represents a number literal.

Attributes:

is_integer (Boolean)
Set if the number is in integer notation.
is_decimal (Boolean)
Set if the number is in decimal notation.
is_exponential (Boolean)
Set if the number is in exponential notation.

htsql.tr.term

This module declares term nodes.

class htsql.tr.term.Joint(lop, rop)

Represents a join condition.

lop (htsql.tr.flow.Code)
The left operand of join expression.
rop (htsql.tr.flow.Code)
The right operand of join expression.
class htsql.tr.term.PreTerm(expression)

Represents a term node.

A term represents a relational algebraic expression. PreTerm is an abstract class, each its subclass represents a specific relational operation.

The term tree is an intermediate stage of the HTSQL translator. A term tree is translated from the expression graph by the compiling process. It is then translated to the frame tree by the assembling process.

The following adapters are associated with the compiling process and generate new term nodes:

Compile: (Flow, CompilingState) -> Term
Inject: (Unit, Term, CompilingState) -> Term

See htsql.tr.compile.Compile and htsql.tr.compile.Inject for more detail.

The following adapter implements the assembling process:

Assemble: (Term, AssemblingState) -> Frame

See htsql.tr.assemble.Assemble for more detail.

Arguments:

expression (htsql.tr.code.Expression)
The expression node which gave rise to the term node; used only for presentation or error reporting.

Other attributes:

binding (htsql.tr.binding.Binding)
The binding node which gave rise to the term node; for debugging.
syntax (htsql.tr.syntax.Syntax)
The syntax node which gave rise to the term node; for debugging.
mark (htsql.mark.Mark)
The location of the node in the original query; for error reporting.
class htsql.tr.term.Term(tag, kids, flow, baseline, routes)

Represents a relational algebraic expression.

There are three classes of terms: nullary, unary and binary. Nullary terms represents terminal expressions (for example, TableTerm), unary terms represent relational expressions with a single operand (for example, FilterTerm), and binary terms represent relational expressions with two arguments (for example, JoinTerm).

Each term represents some flow, called the term flow. It means that, as a part of some relational expression, the term will produce the rows of the flow. Note that taken alone, the term does not necessarily generates the rows of the flow: some of the operations that comprise the flow may be missing from the term. Thus the term flow represents a promise: once the term is tied with some other appropriate term, it will generate the rows of the flow.

Each term node has a unique (in the context of the term tree) identifier, called the term tag. Tags are used to refer to term objects indirectly.

Each term maintains a table of units it is capable to produce. For each unit, the table contains a reference to a node directly responsible for evaluating the unit.

Class attributes:

is_nullary (Boolean)
Indicates that the term represents a nullary expression.
is_unary (Boolean)
Indicates that the term represents a unary expression.
is_binary (Boolean)
Indicates that the term represents a binary expression.

Arguments:

tag (an integer)
A unique identifier of the node.
kids (a list of zero, one or two Term objects)
The operands of the relational expression.
flow (htsql.tr.code.Flow)
The flow represented by the term.
routes (a mapping from htsql.tr.code.Unit to term tag)

A mapping from unit objects to term tags that specifies the units which the term is capable to produce.

A key of the mapping is either a htsql.tr.code.Unit or a htsql.tr.code.Flow node. A value of the mapping is a term tag, either of the term itself or of one of its descendants.

The presence of a unit object in the routes table indicates that the term is able to evaluate the unit. The respective term tag indicates the term directly responsible for evaluating the unit.

A flow node being a key in the routes table indicates that any column of the flow could be produced by the term.

Other attributes:

backbone (htsql.tr.code.Flow)
The inflation of the term flow.
baseline (htsql.tr.code.Flow)
The leftmost axis of the term flow that the term is capable to produce.
offsprings (a dictionary tag -> tag)
Maps a descendant term to the immediate child whose subtree contains the term.
class htsql.tr.term.NullaryTerm(tag, flow, baseline, routes)

Represents a terminal relational algebraic expression.

class htsql.tr.term.UnaryTerm(tag, kid, flow, baseline, routes)

Represents a unary relational algebraic expression.

kid (Term)
The operand of the expression.
class htsql.tr.term.BinaryTerm(tag, lkid, rkid, flow, baseline, routes)

Represents a binary relational algebraic expression.

lkid (Term)
The left operand of the expression.
rkid (Term)
The right operand of the expression.
class htsql.tr.term.ScalarTerm(tag, flow, baseline, routes)

Represents a scalar term.

A scalar term is a terminal relational expression that produces exactly one row.

A scalar term generates the following SQL clause:

(SELECT ... FROM DUAL)
class htsql.tr.term.TableTerm(tag, flow, baseline, routes)

Represents a table term.

A table term is a terminal relational expression that produces all the rows of a table.

A table term generates the following SQL clause:

(SELECT ... FROM <table>)
class htsql.tr.term.FilterTerm(tag, kid, filter, flow, baseline, routes)

Represents a filter term.

A filter term is a unary relational expression that produces all the rows of its operand that satisfy the given predicate expression.

A filter term generates the following SQL clause:

(SELECT ... FROM <kid> WHERE <filter>)
kid (Term)
The operand of the filter expression.
filter (htsql.tr.code.Code)
The conditional expression.
class htsql.tr.term.JoinTerm(tag, lkid, rkid, joints, is_left, is_right, flow, baseline, routes)

Represents a join term.

A join term takes two operands and produces a set of pairs satisfying the given join conditions.

Two types of joins are supported by a join term. When the join is inner, given the operands A and B, the term produces a set of pairs (a, b), where a is from A, b is from B and the pair satisfies the given tie conditions.

A left outer join produces the same rows as the inner join, but also includes rows of the form (a, NULL) for each a from A such that there are no rows b from B such that (a, b) satisfies the given conditions. Similarly, a right outer join includes rows of the form (NULL, b) for each b from B such that there are no corresponding rows a from A.

A join term generates the following SQL clause:

(SELECT ... FROM <lkid> (INNER | LEFT OUTER) JOIN <rkid> ON (<joints>))
lkid (Term)
The left operand of the join.
rkid (Term)
The right operand of the join.
joints (a list of pairs of htsql.tr.code.Code)
A list of pairs (lop, rop) that establish join conditions of the form lop = rop.
is_left (Boolean)
Indicates that the join is left outer.
is_right (Boolean)
Indicates that the join is right outer.
class htsql.tr.term.EmbeddingTerm(tag, lkid, rkid, flow, baseline, routes)

Represents an embedding term.

An embedding term implants a correlated term into a term tree.

An embedding term has two children: the left child is a regular term and the right child is a correlation term.

The joint condition of the correlation term connects it to the left child. That is, the left child serves as the link term for the right child.

An embedding term generates the following SQL clause:

(SELECT ... (SELECT ... FROM <rkid>) ... FROM <lkid>)
lkid (Term)
The main term.
rkid (CorrelationTerm)
The correlated term.
class htsql.tr.term.CorrelationTerm(tag, kid, link, joints, flow, baseline, routes)

Represents a correlation term.

A correlation term connects the child term with a link term using the given joint condition. Note that the link term is not a part of the sub-tree under the correlation term.

A correlation term must always be embedded into the term tree with a EmbeddingTerm instance. The left child of the embedding term must coincide with the link term.

kid (Term)
The operand of the correlation condition.
link (Term)
The term to link to.
joints (a list of pairs of htsql.tr.code.Code)
A list of pairs (lop, rop) that establish join conditions of the form lop = rop.
class htsql.tr.term.ProjectionTerm(tag, kid, kernels, flow, baseline, routes)

Represents a projection term.

Given an operand term and a function on it (called the kernel), the kernel naturally establishes an equivalence relation on the operand. That is, two rows from the operand are equivalent if their images under the kernel are equal to each other. A projection term produces rows of the quotient set corresponding to the equivalence relation.

A projection term generates the following SQL clause:

(SELECT ... FROM <kid> GROUP BY <kernels>)
kid (Term)
The operand of the projection.
kernels (a list of htsql.tr.code.Code)
The kernel expressions.
class htsql.tr.term.OrderTerm(tag, kid, order, limit, offset, flow, baseline, routes)

Represents an order term.

An order term reorders the rows of its operand and optionally extracts a slice of the operand.

An order term generates the following SQL clause:

(SELECT ... FROM <kid> ORDER BY <order> LIMIT <limit> OFFSET <offset>)
kid (Term)
The operand.
order (a list of pairs (code, direction))

Expressions to sort the rows by.

Here code is a htsql.tr.code.Code instance, direction is either +1 (indicates ascending order) or -1 (indicates descending order).

limit (a non-negative integer or None)
If set, the first limit rows of the operand are extracted and the remaining rows are discared.
offset (a non-negative integer or None)
If set, indicates that when extracting rows from the operand, the first offset rows should be skipped.
class htsql.tr.term.WrapperTerm(tag, kid, flow, baseline, routes)

Represents a no-op operation.

A wrapper term represents exactly the same rows as its operand. It is used by the assembler to wrap nullary terms when SQL syntax requires a non-terminal expression.

class htsql.tr.term.PermanentTerm(tag, kid, flow, baseline, routes)

Represents a no-op operation.

A permanent term is never collapsed with the outer term.

class htsql.tr.term.SegmentTerm(tag, kid, elements, flow, routes)

Represents a segment term.

A segment term evaluates the given expressions on the rows of the operand.

A segment term generates the following SQL clause:

(SELECT <elements> FROM <kid>)
kid (Term)
The operand.
elements (a list of htsql.tr.code.Code)
A list of expressions to produce.
class htsql.tr.term.QueryTerm(segment, expression)

Represents a whole HTSQL query.

segment (SegmentTerm or None)
The query segment.

htsql.tr.token

This module defines token types used by the HTSQL scanner.

class htsql.tr.token.Token(value, mark)

Represents a lexical token.

This is an abstract class. To add a concrete token type, create a subclass of Token and override the following class attributes:

name (a string)
The name of the token category. Must be a valid identifier since it is used by the scanner as the name of the pattern group.
pattern (a string)
The regular expression to match the token (in the verbose format).
is_ws (Boolean)
If set, indicates that the token is to be discarded.
is_end (Boolean)
If set, forces the scanner to stop the processing.

When adding a subclass of Token, you may also want to override methods unquote() and quote().

The constructor of Token accepts the following parameters:

value (a Unicode string)
The token value.
mark (htsql.mark.Mark)
The location of the token in the original query.
classmethod unquote(value)

Converts a raw string that matches the token pattern to a token value.

classmethod quote(value)

Reverses unquote().

class htsql.tr.token.SpaceToken(value, mark)

Represents a whitespace token.

In HTSQL, whitespace characters are space, tab, LF, CR, FF, VT and those Unicode characters that are classified as space.

Whitespace tokens are discarded by the scanner without passing them to the parser.

class htsql.tr.token.NameToken(value, mark)

Represents a name token.

In HTSQL, a name is a sequence of alphanumeric characters that does not start with a digit. Alphanumeric characters include characters a-z, A-Z, 0-9, _, and those Unicode characters that are classified as alphanumeric.

class htsql.tr.token.StringToken(value, mark)

Represents a string literal token.

In HTSQL, a string literal is a sequence of arbitrary characters enclosed in single quotes ('). Use a pair of single quote characters ('') to represent a single quote in a string.

class htsql.tr.token.NumberToken(value, mark)

Represents a number literal token.

HTSQL supports number literals in integer, float and scientific notations.

class htsql.tr.token.SymbolToken(value, mark)

Represents a symbol token.

HTSQL employs the following groups of symbols:

comparison operators
=, !=, ==, !==, ~, !~, <, <=, >, >=.
logical operators
!, &, |, ?.
arithmetic operators
+, -, *, /, ^.
assignment operator
:=.
punctuation
(, ), [, ], {, }, ., ,, ->, /, :, $, @.
class htsql.tr.token.EndToken(value, mark)

Represents the end token.

The end token is emitted when the scanner reached the end of the input string and forces the scanner to stop.