monday-item-parser 0.2.15

monday-item-parser is a library used to define Monday items structure in a specific board, and lets the user fetch, create, update and delete items from this board.

Monday Item Parser

Introduction

Monday Item Parser is a library used to define Monday items structure in a specific board, and lets the user fetch, create, update and delete items from this board.

Installation

pip install monday-item-parser

Requirements

• Python >= 3.7
• Monday library for the Mondayhttp client

Changelog

• 0.2.15 (2023-08-03) - Added support for the DropdownLabelField (like the DropdownField but work with the label of the dropdown instead of the index)
• 0.2.14 (2023-08-03) - Added support for the StatusLabelField (like the StatusField but work with the label of the status instead of the index)
• 0.2.13 (2023-08-03) - Added support for fetching group titles, and added the group_title to the Item class
• 0.2.12 (2023-08-03) - Added support for the Location field
• 0.2.10 (2022-09-08) - Added support for the Dropdown field and updated the monday library version
• 0.2.9 (2022-04-22) - Fixed a bug in Long Text field
• 0.2.8 (2022-04-22) - Added support for Long Text field
• 0.2.7 (2022-03-30) - Bumped version because of workflow problems (again :()
• 0.2.5 (2022-03-30) - Added mirror field to readme.
• 0.2.4 (2022-03-30) - Added support for mirror (lookup) fields.
• 0.2.3 (2021-01-16) - Same as 0.2.2, but got some problems with PyPI and Github Workflows again. :(
• 0.2.2 (2021-01-16) - Added support for search items by column value
• 0.2.1 (2021-01-16) - Added hooks for field values.
• 0.2.0 (2021-01-14) - Updated the item's field value set method to be explicit (without calling .value)
• 0.1.2 (2021-01-13) - Fixed a small bug in the Item::__init__ function
• 0.1.1 (2021-01-13) - Still first release, but got some problems with PyPI and Github Workflows
• 0.1.0 (2021-01-13) - First release

Todo List

• Create fetch_groups function to an item that returns the id along with the group title
• Add to the create_item function the option to add the item to a group by its title, not by id
• Add custom exceptions for common errors:
  • Budget Exhausted Error
  • Invalid Group Id (in item creation)

How to use

Items

Items are the full board item structure, built from fields.

from monday import MondayClient
from monday_item_parser import Item, CheckboxField


board_id = 1234
monday_client = MondayClient("MONDAY_API_KEY_HERE")


class MyItem(Item, board_id=board_id, monday_client=monday_client):
    checkbox_example = CheckboxField()

    # Can be declared either as a type or as an instance, so this is good as well:
    checkbox_example = CheckboxField

NOTE: The variables in your item class must be named EXACTLY the same as in your monday board but in lower-case and replace spaces into underscore. For example a column in Monday with the name My Nice Column will must be defined in your item class my_nice_column.

Fetch items from board

>>> for item in ExampleItem.fetch_items_from_board():
>>>     print(item)

Fetch items by column value

You can fetch all of the items from board by a specific column value filter.

# Let's filter all of the items with a Status column named "status_example" that holds the label "Done"
for item in ExampleItem.fetch_items_by_column_value(status_example="Done"):
    print(item)

More info about supported and unsupported fields you can search by here.

Field Type	Field Value to Search By
Text	str The text to search
Status	str The label to search
Numbers	Either int or float. The value to search
Date	datetime.datetime The date (year, month and day) to search by
Phone	Phone (internal library class) The phone number to search by
Country	str The country code to search by
Email	str The email to search by
Timeline	Timeline (internal library class) The start and end date to search by
Link	Link (internal library class) The display text (not the actual url link) to search by
Mirror	str The text to search
Long Text	str The text to search

Create Item

NOTE: You can only create an item that isn't fetched from the board / already created using this exact function. If you want to create a new item that was fetched from the board you should use the duplicate_item function

>>> item = MyItem(checkbox_example=True)
>>> item.name = "My First Example"
>>> item.create_item()

Duplicate Item

NOTE: You can only duplicate an item that was fetched from the board / created by the create_item function.

>>> new_item = item.duplicate_item()

Update Item

NOTE: You can only update an item that was fetched from the board / created by the create_item function.

>>> new_item.name = 'Updated Item'
>>> new_item.checkbox_example = False
>>> new_item.update_item()

Delete Item

NOTE: You can only delete an item that was fetched from the board / created by the create_item function.

>>> new_item.delete_item()

Get Group Ids in Board

>>> for group_id in ItemExample.fetch_group_ids():
>>>     print(group_id)
"topics"
"group_title"

Hook Field Values

A hook can be registered for whenever the value on a specific field is changed.

from monday_item_parser import *

class ItemWithFieldHook(Item, monday_client=client, board_id=testing_board_id):
    status_example = StatusField
    checkbox_example = CheckboxField

    @field_updated_hook(status_example)
    def status_example_hook(self):
        if self.status_example.value is not None:
            # In the hook you must update the value with the
            # `.value` attribute if you don't want to trigger the hook again
            self.status_example.value += 1
        else:
            self.status_example.value = 0

item = ItemWithFieldHook()
# Trigger the hook by setting the value WITHOUT the `.value` attribute
item.status_example = 5
assert item.status_example.value == 6

Fields

Field is actually an Monday board's item column. The currently supported types are:

Monday Column Type	Library Class Name
Checkbox	CheckboxField
Country	CountryField
Date	DateField
Email	EmailField
Link	LinkField
Number	NumberField
People	PeopleField
Phone	PhoneField
Status	StatusField
Tags	TagsField
Text	TextField
Timeline	TimelineField
Mirror	MirrorField
Long Text	LongTextField

Full Example

class ItemExample(Item, monday_client=client, board_id=testing_board_id):
    status_example = StatusField
    date_example = DateField
    checkbox_example = CheckboxField
    country_example = CountryField
    email_example = EmailField
    link_example = LinkField
    numbers_example = NumberField
    people_example = PeopleField
    phone_example = PhoneField
    tags_example = TagsField
    text_example = TextField
    timeline_example = TimelineField
	mirror_example = MirrorField
    long_text_example = LongTextField

item = ItemExample()

# Setting the values of an item
item.item_name = "Aviv Atedgi"
item.status_example = "Working on it"
item.date_example = datetime.now()
item.checkbox_example = True
item.country_example = "IL"
item.email_example = "[e-mail]"
item.link_example.value.url = "https://www.github.com/avivatedgi"
item.link_example.value.text = "My Github Profile"
item.link_example = LinkField(url="https://www.google.com", text="Google It")
item.numbers_example = 192.4
item.people_example = [Person(25200525)]
item.phone_example.value.country_code = "IL"
item.phone_example.value.phone = "0501234567"
item.phone_example = PhoneField(phone="12123123123", country_code="US")
item.tags_example = [12808387]
item.text_example = "My Cool Text Example"
item.timeline_example.value.start = datetime.strptime("2000-05-01", "%Y-%m-%d")
item.timeline_example.value.end = datetime.now()
item.timeline_example = TimelineField(
    start=datetime.strptime("2005-04-12", "%Y-%m-%d"),
    end=datetime.now(),
)
item.long_text_example = "Hello\nWorld"

# Getting the values of an item
print("Status Example =", item.status_example.value)
print("Date Example =", item.date_example.value)
print("Checkbox Example =", item.checkbox_example.value)
print("Country Example =", item.country_example.value)
print("Email Example =", item.email_example.value)
print("Link Example URL =", item.link_example.value.url)
print("Link Example Text =", item.link_example.value.text)
print("Numbers Example =", item.numbers_example.value)
print("People Example =", item.people_example.value)
print("Phone Example Country Code =", item.phone_example.value.country_code)
print("Phone Example Phone Number =", item.phone_example.value.phone)
print("Tags Example =", item.tags_example.value)
print("Text Example =", item.text_example.value)
print("Timeline Example Start Date =", item.timeline_example.value.start)
print("Timeline Example End Date =", item.timeline_example.value.end)
print("Mirror Example = ", item.mirror_example.value)
print("Long Text Example = ", item.long_text_example.value)

Special Thanks

• Hydration (Michael Shustin) For the idea of the items metaclass
• Monday (ProdPerfect) For the Monday client use in the library