Release v2.0.0

There are a lot of new features to be found in version 2.0.0, including keyword arguments, arithmetic in arguments, many new specials, and bug fixes.

• 2.0.0
  • Numerous new language features
    • Support for arithmetic in arguments. The supported operators are
      -, +, *, /, // (floor division), ** (exponentiation), and %. The operators can be used any
      place a value is valid within an argument, such as $special(14000 * 2), $special(@value // 2),
      $special([1, 1+1, 1+2]). The order of operations follows typical precedence, and arithmetic
      can be nested in ().
    • Support for keyword arguments:$index("value", fallback=12)
    • Whitespace is allowed in a lot more places in a query now, which is very helpful since both
      JavaScript and Python support multi-line strings.
  • Performance increase for cases were a Query field doesn't have any specials. A faster parsing
    method can be used for about a 40x performance increase in creating the Query object. Note, this
    just speeds up Query creation and not the speed of .single(), .many(), etc.
  • Added functionality so that Filter values can be queries.
    • Using JSON: { field: <field>, operator: <op>, value: { query: <value query> } }
    • Using Key: Key(<field>).<op>(Key(<value_query>))
    • For example: Key("tag.tag1").gt(Key("tag.tag2"))
  • Four new filters: subset, !subset, superset, !superset. These should be read
    field value <op> filter value, so subset means all of the values returned from the field query
    are in the filter value, which allows better filtering when both the field query and value are iterable.
  • Many new specials
    • $key_of_min_value - Gets the key of the min value in an dict/map/object
    • $key_of_max_value - Gets the key of the max value in an dict/map/object
    • $time_part(part) -> int - Get a specific part of a datetime/moment object. Valid values for part are as follows:
      • 'millisecond'
      • 'second'
      • 'minute' - Starting from 0
      • 'hour' - Starting from 0
      • 'day' - Day of month, starting from 1
      • 'month' - Month of year, starting from 1
      • 'year'
      • 'dayOfWeek' - Value in 0-6, corresponding to Monday-Sunday
      • 'dayOfYear' - Day of year, starting from 1
    • $min and $max
    • $arith(op, arg_value) - Perform an arithmetic operation on the current value. op can be
      any of the support math operators.
    • $lowercase, $uppercase, and $titlecase
    • $filter(field, op, value, single=true) OR $filter({<filter>}, single=true) OR
      $filter([<filters>], single=true) - Allow a single value or list of values to be filtered.
      The filters should be formatted that same way they are for Filter.
    • $pipeline(pipeline) - Apply multiple specials to value in a given order. Can be very useful
      when used in conjunction with $map to apply multiple specials at once. pipeline must be of format:

[
    <special>

    OR

    [<special>, arg1, arg2, ..., (optional) map/object/dict of keyword arguments],
    ...
]

for example

$pipeline([
    ['index', 'balance'],
    ['range', 1],
    ['replace', {'old': ',', 'new': ''}],
    ['float']
])

is the same as
$index("balance").$range(1).$replace(old=",", new="").$float

• Updates to old specials
  • $index(i, fallback=null, extended=false) - added extended argument to allow
    $index to support any valid JQL query for i if extended=true
• Bug fixes
  • Fixed issue with filters not shortcutting properly
  • Fixed Python issue with $print
  • Fixed issues with $fallback with Filter and Formatter
  • Fixed issue causing an error when trying to use an integer value in
    $sort and $group_by

Release v1.1.5

• 1.1.5

  • Unify README between Python and JavaScript versions
  • Expand documentation

• 1.1.4

  • Added $value_map, which allows the values on an map/dict/object to be modified with a special, either in-place
    or on a duplicate
  • Exposed context so additional fields can manually be put into the current query space. This was already
    being used by $store_as. context can be passed to any .single() or .many() call.
  • Additionally, Filter.many() is now placing INDEX into the query space to allow
    items to be filtered by their 0-based index

Release v1.1.3

• 1.1.3
  • Changed the behavior of Query(""), from returning the fallback value, to returning the source data element itself.
    For example, Query("").single(data) == data.
  • Added SpecialNotFoundError, which is raised when an invalid special is queried. Can be imported as
    from jtools import SpecialNotFoundError
  • Added new specials
  • $store_as(name) Store the current query value in the current context for later use in the query. This does not
    change the underlying data being queried.
  • $group_by(key="", count=false) Take an incoming list and group the values by the specified key.
    Any valid JQL query can be used for the key, so "" means the value itself. The result by default will be
    keys to a list of values. However, if count=true, then the result will be keys to the number of elements with each
    key.
  • $sort(key="", reverse=false) Sort an incoming list of values by a given key which can be any valid JQL query.
    By default, key="" means the top-level value will be sorted on.
  • $dict Take an incoming list of (key, value) pairs and make a dict out of them.
  • $join_arg(arg, sep=', ') Similar to $join except this operates on an argument instead of the query value.
    Essentially a shortened form of $inject(arg).$join(sep).
  • Changed the underlying special function definition to now include the keyword argument context. This argument is
    implemented to only be accessed by name to avoid collision if the user provides too many arguments in their query.
    The purpose of the context is to support specials adding values temporarily to the data
    namespace of the query, like $store_as does.

Release v1.1.2

v1.1.1 was not released properly - below is the changelog for both releases

• 1.1.2

  • Minor changes to documentation
  • Mostly just to get version back on track with repository

• 1.1.1

  • Add antlr4-python3 requirement to setup.py so that installation will get the needed dependencies
  • Change JQL so that field and special names must only contain [-a-zA-Z0-9_]. $index can be used to get fields
    with prohibited characters. The change was to support more formatting use-cases, like Age: @age, DOB: @dob, which
    previously would have failed because the , would have been considered part of the field name.
  • Change Formatter so that fallback is just a string that is substituted for invalid queries, instead of being
    the entire return value. Previously, "Age: @missing" would result in None, not it results in "Age: <missing>".
    This change allows for better debugging as it becomes clear exactly which queries are failing.
  • Add function docstrings

Release v1.1.0

• Rename Getter to Query to more accurately describe what the class does
• Migrate queries to use JQL
  • The migration opens the door to nested queries in Query, allowing queries, prefixed with @ to be used as arguments to specials, or even as values in the supported argument data structures
  • Special arguments are no longer parsed as JSON, allowing features like sets, query nesting, and support for single and double quoted strings.
  • Formatter no longer uses {{}} to surround queries. Instead, all queries must be prefixed with @, so "{{name}} {{age}}" -> "@name @age". @@ must be used to get a literal @ in a formatted string: "bob@@gmail.com" -> "bob@gmail.com"
  • Formatter got about a 2x performance boost
• Added $wrap(prefix, suffix) to combine $prefix and $suffix
• Added $remove_nulls
• Added $lookup(map, fallback=None)
• Added $wildcard(next, just_value=True), which allows level of nesting to be "skipped", such that a list of sub-values where next is present
• Added a fallback argument to $index
• Added $print to display the current value in the query
• Added $inject to allow any valid argument value to be injected into the query to be accessed and transformed by subsequent fields and specials

Release v1.0.6

Major updates include more tests and aligning more closely with the JavaScript version of this
project: https://github.com/BlendingJake/JTools-JS

• Add === and !== to match the strict equality checking needed in the JS version.
  The methods seq and sne have been added to Key to correspond with the new filters. === is the same as == and !== in the same as != in the Python version.

• Rename null -> !present and !null -> present. Corresponding methods have been renamed
  to not_present and present. This filter will catch values that are null or undefined.

• Make membership filters (in, contains, !in and !contains) work properly with
  strings, lists, dicts, and sets.

• Remove $datetime. See below for replacement.

• Add $call and $attr for calling a function and accessing an attribute. Can be used to replace
  $datetime functionality.

• Remove Formatter.format and add Formatter.single and Formatter.many to be consistent across
  other classes and support formatting arrays of items.

• Add more tests to increase coverage and do basic performance testing

Release v1.0.5

1.0.5

• Query strings can now start with specials to allow operations on the entire object being passed.
• Bug fixes and more unit tests

Release v1.0.4

• Added new specials, mostly relating to time
  • $parse_timestamp
  • $datetime
  • $strptime
  • $strftime
• Added not filtering and the interval and !interval operators
• Made Filter consistent with Getter by removing .filter() and adding
  .single() and .many()
• Added fallback to Getter
• added numerous unit tests

Release v1.0.3

• Rename Getter.get to Getter.single
• Add Getter.many
• Support getting multiple fields at once by changing Getter to allow Getter(<field>) and Getter([<field>, <field>, ...])
• Change Filter's before for when there are no filters. Now, by default, all items will be returned unless Filter(..., empty_filters_response=False)

Release v1.0.2

• add three new specials: $not, $ternary(if_true, if_false, strict=False), and $strip. The first two are intended to help with handling booleans, the other strips whitespace off of strings
• added in some tests and test data
• update docs, documenting new features and correcting some basic mistakes