Pyttman

**2022-02-28**

This release further improves the new Plug-And-Play EntityField classes used in the EntityParser API in Pyttman; further empowering developers to quickly find words of interest in Messages from users, using the declarative EntityParser API.

:star2: News
* **Major refactoring of internal API algorithms to improve speed and**
**functionality of the EntityParser API.**

* **New EntityField: `BoolEntityField`**

The `BoolEntityField` provides a boolean entity on whether a pattern
was matched in an incoming message, or not. This is useful for
scenarios when the word itself in the message is not of interest, but
only the fact if it occurred in the message at all.

python
message.entities["answer_in_spanish"] will be True or False
depending on whether the message contains the word 'spanish'

class EntityParser:
answer_in_spanish = BoolEntityField(message_contains=("spanish",))




* **Added 2 new Identifier classes**

* `FloatIdentifier` and `NumberIdentifier` are both Identifier classes to
find numbers, and are direct references to `IntegerIdentifier` but
offers more naming options.



* **New settings.py option**
The option to log to STDOUT in addition to the default log file has been added. To use it, define `LOG_TO_STDOUT = True` in the Pyttman app `settings.py` file.



* **Introducing Pyttman Middleware**

The Pyttman framework is growing. To make it easier to extend functionality for developers using Pyttman, we have abstracted the layer for message routing to a new layer; the Middleware layer.

This allows for future extension of the Middleware layer, adding options for message filtering and reply relaying through event schedulers and much more. As of this release, nothing has really changed in the usagae experience, except for the deprecation warning on importing the `FirstMatchingRouter` through the legacy import path, since it was moved. No direct action is required for apps upgrading from older versions.

**🐛 Splatted bugs and corrected issues**
* **Fixes [57](https://github.com/dotchetter/Pyttman/issues/57) - Logs don't show in Heroku**

> This issue traces back to the way certain platform log the STDOUT and
> STDERR streams by default. We added a new optional setting which allows
> apps to also log to STDOUT: `LOG_TO_STDOUT = True` in `settings.py` in a
> Pyttman app will resolve this issue.

👀 Changes

* **Pyttman 1.1.10 requires Python 3.10 at minimum.**

Changes to the type hinting in several places in the source code means that Python versions below 3.10 are not supported.

> Note! This is a breaking change.

* **The usage of `Parser` classes in `EntityParser` classes in `Intent`**
**classes have been deprecated and are no longer supported.** Refer to the
`EntityField` types for direct replacements. `EntityField` classes
implement the same interface as the `Parser` classes.

> Note! This is a breaking change.

* **`Identifier` classes are moved from `pyttman.core.parsing.identifiers` to `pyttman.core.entity_parsing.identifiers` module.**

> Note! This is a breaking change.

* **The `ChoiceParser` class is deleted, in favor of using `TextEntityField` with `valid_strings` as the subset of available options.**

> Note! This is a breaking change.

* **Reverts the change made in** `1.1.9` with Entities: `message.entities` is
now back to being a dict of direct entity values, not `Entity` classes.
The reason for this revert was the repetitive pattern of using the
`.value` property in apps on properties, and not doing so would cause
exceptions.

> Note! This is a breaking change.

* **The Middleware API in Pyttman results in a move of the** `FirstMatchingRouter` class, commonly referenced in Pyttman apps in `settings.py` under `ROUTER_CLASS`. The class is now available under `pyttman.core.middleware.routing.FirstMatchingRouter` but is still available for import at the older import path, `pyttman.core.parsing.routing.FirstMatchingRouter` for the time being, which results in a deprecation warning to STDOUT.

2021-12-24

This release is a hotfix release of a critical bug in the Pyttman cli,
rendering apps unable to start in client mode, rendering them unusable.

**🐛 Splatted bugs and corrected issues**
* Fixes [55](https://github.com/dotchetter/Pyttman/issues/55) - pyttmancli runclient not working

2021-12-11

This release includes bug fixes but also some new cool features.

:star2: News
* Entities are now accessed on the `Message` object in Intents instead of
being accessed on the Intent itself.
Accessing Entities on the Intent is supported until 1.2.0 and will raise
a deprecation warning.
* **EntityField** classes provide an easier and more efficient way to find
values of interest in messages from users.

**🐛 Splatted bugs and corrected issues**
* Fixes [47](https://github.com/dotchetter/Pyttman/issues/47) - Strings with different case from otherwise identical values in lead/trail/exclude are not truncated
* Fixes [48](https://github.com/dotchetter/Pyttman/issues/48) - ChoiceParser can't parse choices when capitalized
* Fixes an issue with type hinting referring to the `MessageMixin` in `Intent.respond()` implementation -> Corrected to now hinting `Message`.

👀 Changes
* Entities are no longer `str`, but `Entity` instances. To fetch the value
of the entity itself as previously done by `name = self.entities.get
("name")` is now instead done as `name = self.entities.get("name").value`

This release includes bug fixes and internal improvements mainly.

Although the points listed below may seem minor, we've rewired and tested this release probably better than any other up to this point :happy:



:star2: News

* **New setting in `settings.py`**

`settings.py` in Pyttman apps now have the `DEV_MODE` flag for users to toggle.

> Note! When you run an app in dev mode using `pyttman dev <app_name>`, it is automatically set to `True` regardless of `settings.py`.

*Example*:

python
In settings.py
DEV_MODE = True

Somewhere in the app logic
if pyttman.settings.DEV_MODE is True:
print("Some debug statement")




👀 Changes

* The `BaseClient` class is moved in Pyttman, which changes the import path for the class:

`pyttman.clients.builtin.base.BaseClient` becomes `pyttman.clients.base.BaseClient` .

* Vast improvements to the Pyttman CLI tool

The administrative CLI tool `pyttman` for creating, bootstrapping and
debugging Pyttman apps has been rewritten using the Pyttman framework
itself to build Intents, read from the terminal shell.



**🐛 Splatted bugs and corrected issues**

* Fixes [35](https://github.com/dotchetter/Pyttman/issues/35) with internal improvements to the EntityParser algorithm in how it considers the resolution order of how entity strings are parsed, identified and later stored in `self.entities` in `Intent` classes.
* Fixes [40](https://github.com/dotchetter/Pyttman/issues/40) - `pyttman dev <app name>` now works without providing a Client class.

This release is a hotfix release, adressing issues using the `runclients` command with `pyttman` cli tool on linux and unix based systems.

👀 Changes
* Clients are no longer started in parallel using Threading due to issues with security and runtime on unix and linux based systems. Observe that in your `settings.py` file, the `CLIENTS` field is replaced by a `CLIENT` field, which is a single dictionary containing the client configuration for your app. This was necessary for multiple reasons, one being the complexity of pickling application logic to run them in parallel using a process pool instead of threading, to solve [bug 33](https://github.com/dotchetter/Pyttman/issues/33). We're sorry about the inconvenience this may cause for your development and the experience with Pyttman so far. We're still learning.
It seems that this approach works well with deploying apps using Docker, as you can create containers using different settings for various platforms and support multiple platforms in this manner.

> Note! This is a breaking change.

* The Pyttman CLI "`pyttman`" argument for running client has changed from `runclients` to just `runclient`, indicating a `single` client configuration in settings.py

> Note! This is a breaking change.

🐛 Splatted bugs and corrected issues
- Fixes an [issue](https://github.com/dotchetter/Pyttman/issues/33), causing the `runclients` argument not to start apps as intended on linux and unix based operating systems.


- Improves how settings are loaded, using the new [Setting](https://github.com/dotchetter/Pyttman/blob/c9f4433d3221b8fd30d71cecdece84b0bb05a4db/pyttman/core/internals.py#L46) class.
You still access your settings defined in `settings.py` using `pyttman.settings` in your app.

🤗 New features and changes
* The `Feature` class is renamed to `Ability` for better semantic similarity to the general standard of terminology.

> Note! This is a **breaking** change.


* The `Command` class is renamed to `Intent` for better semantic similarity to the general standard of terminology.

> Note! This is a **breaking** change.


* `pyttman-cli` is renamed to just `pyttman` for increased simplicity.

> Note! This is a **breaking** change.


* The reference to `Feature` in `Intent` classes (previously `Command` classes) - is removed.
this means that the `Storage` object previously accessed through `self.feature.storage` can no longer be accessed this
way. Instead, the `Ability` is no longer referenced inside `Intent` classes for cleaner OOP relations.
**However**, the `Storage` object is still available in `Intent` classes, of course. It is accessed using `self.storage` both in the `Ability`
and in `Intent` classes.

> Note! This is a **breaking** change.


* The NLU component `EntityParser` class of `Intent` classes has been improved, and no longer identifies one entity more than once. It is also a lot smarter in how it traveres the message in order to find the data of interest.


* The `EntityParser` class must no longer inherit from `EntityParserBase` or `Intent.EntityParser`, metaclassing is internally handeled.


* The `CommandProcessor` class which was deprecated in version 1.1.4, is removed.


* The `Callback` class which was deprecated in 1.1.4, is removed.


* The `Interpretation` class which was deprecated in 1.1.4, is removed.


* Methods associated with legacy classes from the `Intent` and `Ability` classes internally, have been removed


* The new `ReplyStream` Queue-like object offers you the ability to return **multiple** response messages in a single object from Intents.
The `ReplyStream` will wrap your strings or other objects as `Reply` objects if compatible, and the client will post each of these elements as separate messages in the client.


* The `pyttman.schedule.method` api method no longer requires the use of the `async_loop` argument if the function to be scheduled is asynchronous, but rather acquires the running loop through `asyncio.get_running_loop()`. If no running loop is identified, it will automatically run the asynchronous function using `asyncio.run`.


* Identifier class `DateTimeStringIdentifier` has added regex patterns to also identify strings with a date stamp, without a specific time.
For example, in a message like: `On that fateful night of 1986/04/26 (...)` - the `DateTimeStringIdentifier` would now find `1986/04/26` as a valid entity.


🐛 Splatted bugs and corrected issues

* Fixes an [issue](https://github.com/dotchetter/Pyttman/issues/30) where line separations in `Reply` objects were not present when the data was displayed in applications such as DIscord or the Cli client terminal shell. These are now present.


* Fixes an [issue](https://github.com/dotchetter/Pyttman/issues/24) where clients could not communicate any errors upon startup. These are now showed through user warnings.


* Fixes an [issue](https://github.com/dotchetter/Pyttman/issues/31) where one element in a message would end up multiple times in `self.entities` incorrectly


* Fixes an [issue](https://github.com/dotchetter/Pyttman/issues/32) where strings defined in `lead` and `trail` in `Intent` classes were case-sensitive - they are not anymore.


* Fixes an issue where an entity parsed using a `ChoiceParser` would
be stored as the casefolded variant. With this correction, identification
is done case-insensitively, and the defined value in the `ChoiceParser.choices`
is the one present in `self.entites`, when a match occurs.


* Fixes an issue with the `CapitalizedIdentifier` identifier class, as it would not grant
all-caps words as valid.
------