Category¶
Todo
Docstrings (module, model, operations, utilities)
Models¶
- class indico.modules.categories.models.categories.Category(**kwargs)¶
An Indico category.
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- ATTACHMENT_FOLDER_ID_COLUMN = 'category_id'¶
The name of the AttachmentFolder column pointing to to the object’s ID
- access_key = None¶
- acl_entries¶
- allow_no_access_contact = True¶
Whether the object can have contact information shown in case of no access
- allow_relationship_preloading = True¶
Whether relationship preloading is allowed. If disabled, the on-load event that populates relationship from the preload cache is not registered.
- can_create_events(user)¶
Check whether the user can create events in the category.
- can_propose_events(user)¶
Check whether the user can propose move requests to the category.
- property chain_query¶
Get a query object for the category chain.
The query retrieves the root category first and then all the intermediate categories up to (and including) this category.
- children¶
- property deep_children_query¶
Get a query object for all subcategories.
This includes subcategories at any level of nesting.
- default_badge_template¶
- default_badge_template_id¶
- default_event_themes¶
- default_render_mode = 2¶
- default_ticket_template¶
- default_ticket_template_id¶
- disallowed_protection_modes = frozenset({})¶
The protection modes that are not allowed. Can be overridden in the model that is using the mixin. Affects the table structure, so any changes to it should go along with a migration step! By default, the public mode is disallowed since it does not make much sense in most cases to make something public even though its parent object is private (or inheriting).
- property display_tzinfo¶
The tzinfo of the category or the one specified by the user.
- property effective_icon_url¶
Get the HTTP URL of the icon (possibly inherited).
- event_creation_mode¶
- event_creation_notification_emails¶
- event_message¶
- event_message_mode¶
Get all hidden events within the given category and user.
- classmethod get_icon_data_cte()¶
- classmethod get_protection_cte()¶
- get_protection_parent_cte()¶
- classmethod get_root()¶
Get the root category.
- classmethod get_subtree_ids_cte(ids)¶
Create a CTE for a category subtree.
This CTE contains a single
id
column that contains all the specified IDs and those of all their subcategories.This is likely to be much more performant than get_tree_cte when the query is used with LIMIT, especially in large databases.
- classmethod get_tree_cte(col='id')¶
Create a CTE for the category tree.
The CTE contains the following columns:
id
– the category idpath
– an array containing the path from the root tothe category itself
is_deleted
– whether the category is deleted
- Parameters
col – The name of the column to use in the path or a callable receiving the category alias that must return the expression used for the ‘path’ retrieved by the CTE.
- static get_visible_categories_cte(category_id)¶
Get a sqlalchemy select for the visible categories within the given category, including the category itself.
- property has_effective_icon¶
- property has_icon¶
- property has_logo¶
- icon¶
- icon_metadata¶
- property icon_url¶
Get the HTTP URL of the icon.
- id¶
- inheriting_have_acl = True¶
Whether objects with inheriting protection may have their own ACL entries (which will grant access even if the user cannot access the parent object).
- is_deleted¶
- is_descendant_of(categ)¶
- property is_empty¶
- is_flat_view_enabled¶
- is_root¶
- locator()¶
Define a smart locator property.
This behaves pretty much like a normal read-only property and the decorated function should return a dict containing the necessary data to build a URL for the object.
This decorator should usually be applied to a method named
locator
as this name is required for get_locator to find it automatically when just passing the object.If you need more than one locator, you can define it like this:
@locator_property def locator(self): return {...} @locator.other def locator(self): return {...}
The
other
locator can then be accessed by passingobj.locator.other
to the code expecting an object with a locator.
- log(realm, kind, module, summary, user=None, type_='simple', data=None, meta=None)¶
Create a new log entry for the category.
- Parameters
realm – A value from
CategoryLogRealm
indicating the realm of the action.kind – A value from
LogKind
indicating the kind of the action that was performed.module – A human-friendly string describing the module related to the action.
summary – A one-line summary describing the logged action.
user – The user who performed the action.
type – The type of the log entry. This is used for custom rendering of the log message/data
data – JSON-serializable data specific to the log type.
meta – JSON-serializable data that won’t be displayed.
- Returns
The newly created EventLogEntry
In most cases the
simple
log type is fine. For this type, any items from data will be shown in the detailed view of the log entry. You may either use a dict (which will be sorted) alphabetically or a list ofkey, value
pairs which will be displayed in the given order.
- logo¶
- logo_metadata¶
- property logo_url¶
Get the HTTP URL of the logo.
- notify_managers¶
- nth_parent(n_categs, fail_on_overflow=True)¶
Return the nth parent of the category.
- Parameters
n_categs – the number of categories to go up
fail_on_overflow – whether to fail if we try to go above the root category
- Returns
Category object or None (only if
fail_on_overflow
is not set)
- own_no_access_contact¶
- property own_visibility_horizon¶
Get the highest category this one would like to be visible from (configured visibility).
- property parent_chain_query¶
Get a query object for the category’s parent chain.
The query retrieves the root category first and then all the intermediate categories up to (excluding) this category.
- parent_id¶
- position¶
- possible_render_modes = {RenderMode.markdown}¶
- protection_mode¶
- property protection_parent¶
The parent object to consult for ProtectionMode.inheriting.
- query: IndicoBaseQuery¶
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- property real_visibility_horizon¶
Get the highest category this one is actually visible from (as limited by categories above).
- render_mode = 2¶
- suggestions_disabled¶
- timezone¶
- title¶
- property tzinfo¶
- property url¶
- visibility¶
- property visibility_horizon_query¶
Get a query object that returns the highest category this one is visible from.
- property visible_categories_query¶
Get a query object for the visible categories within this category, including the category itself.
- class indico.modules.categories.models.categories.EventCreationMode(value)¶
An enumeration.
- moderated = 2¶
- open = 3¶
- restricted = 1¶
- class indico.modules.categories.models.categories.EventMessageMode(value)¶
An enumeration.
- danger = 3¶
- disabled = 0¶
- info = 1¶
- warning = 2¶
- class indico.modules.categories.models.principals.CategoryPrincipal(**kwargs)¶
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- allow_category_roles = True¶
Whether it should be allowed to add a category role
- allow_networks = True¶
Whether it should be allowed to add an IP network.
- category_id¶
The ID of the associated event
- category_role¶
- category_role_id¶
- email = None¶
- event_role = None¶
- event_role_id = None¶
- full_access¶
- id¶
The ID of the acl entry
- ip_network_group¶
- ip_network_group_id¶
- local_group_id¶
- multipass_group_name¶
- multipass_group_provider¶
- permissions¶
- principal_backref_name = 'in_category_acls'¶
The name of the backref added to User and LocalGroup. For consistency, it is recommended to name the backref
in_foo_acl
with foo describing the ACL where this mixin is used.
- principal_for = 'Category'¶
The model for which we are a principal. May also be a string containing the model’s class name.
- query: IndicoBaseQuery¶
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- read_access¶
- registration_form = None¶
- registration_form_id = None¶
- type¶
- unique_columns = ('category_id',)¶
The columns which should be included in the unique constraints. If set to
None
, no unique constraints will be added.
- user_id¶
- class indico.modules.categories.models.settings.CategorySetting(**kwargs)¶
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- category¶
- category_id¶
- id¶
- module¶
- name¶
- query: IndicoBaseQuery¶
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- value¶
Operations¶
- indico.modules.categories.operations.create_category(parent, data)¶
- indico.modules.categories.operations.delete_category(category)¶
- indico.modules.categories.operations.move_category(category, target_category)¶
- indico.modules.categories.operations.update_category(category, data, *, skip=(), _extra_log_fields=None)¶
- indico.modules.categories.operations.update_category_protection(category, data, *, _extra_log_fields=None)¶
- indico.modules.categories.operations.update_event_move_request(request, accept, reason='')¶
Utilities¶
- indico.modules.categories.util.can_create_unlisted_events(user)¶
- indico.modules.categories.util.format_visibility(category_or_event, visibility)¶
- indico.modules.categories.util.get_attachment_count(category_id=None)¶
Get the number of attachments in events in a category.
- Parameters
category_id – The category ID to get statistics for. Attachments from subcategories are also included.
- Returns
The number of attachments
- indico.modules.categories.util.get_category_stats(category_id=None)¶
Get category statistics.
This function is mainly a helper so we can get and cache all values at once and keep a last-update timestamp.
- Parameters
category_id – The category ID to get statistics for. Subcategories are also included.
- indico.modules.categories.util.get_contribs_by_year(category_id=None)¶
Get the number of contributions for each year.
- Parameters
category_id – The category ID to get statistics for. Contributions from subcategories are also included.
- Returns
A dictionary mapping years to contribution counts.
- indico.modules.categories.util.get_events_by_year(category_id=None)¶
Get the number of events for each year.
- Parameters
category_id – The category ID to get statistics for. Events from subcategories are also included.
- Returns
A dictionary mapping years to event counts.
- indico.modules.categories.util.get_image_data(image_type, category)¶
- indico.modules.categories.util.get_min_year(category_id=None)¶
Get the min year.
- Parameters
category_id – The category ID to get statistics for.
- Returns
The year.
- indico.modules.categories.util.get_upcoming_events()¶
Get the global list of upcoming events.
- indico.modules.categories.util.get_visibility_options(category_or_event, allow_invisible=True)¶
Return the visibility options available for the category or event.
- indico.modules.categories.util.serialize_category_role(role, legacy=True)¶
Serialize role to JSON-like object.
- indico.modules.categories.serialize.serialize_categories_ical(category_ids, user, event_filter=True, event_filter_fn=None, update_query=None)¶
Export the events in a category to iCal.
- Parameters
category_ids – Category IDs to export
user – The user who needs to be able to access the events
event_filter – A SQLalchemy criterion to restrict which events will be returned. Usually something involving the start/end date of the event.
event_filter_fn – A callable that determines which events to include (after querying)
update_query – A callable that can update the query used to retrieve the events. Must return the updated query object.
- indico.modules.categories.serialize.serialize_category(category, with_favorite=False, with_path=False, parent_path=None, child_path=None)¶
- indico.modules.categories.serialize.serialize_category_atom(category, url, user, event_filter)¶
Export the events in a category to Atom.
- Parameters
category – The category to export
url – The URL of the feed
user – The user who needs to be able to access the events
event_filter – A SQLalchemy criterion to restrict which events will be returned. Usually something involving the start/end date of the event.
- indico.modules.categories.serialize.serialize_category_chain(category, include_children=False, include_parents=False)¶
Settings¶
- class indico.modules.categories.settings.CategorySettingsProxy(module, defaults=None, strict=True, acls=None, converters=None)¶
Proxy class to access category-specific settings for a certain module.
- delete(category, *names)¶
Delete settings.
- Parameters
category – Category (or its ID)
names – One or more names of settings to delete
- delete_all(category)¶
Delete all settings.
- Parameters
category – Category (or its ID)
- get(category, name, default=<object object>)¶
Retrieve the value of a single setting.
- Parameters
category – Category (or its ID)
name – Setting name
default – Default value in case the setting does not exist
- Returns
The settings’s value or the default value
- get_all(category, no_defaults=False)¶
Retrieve all settings.
- Parameters
category – Category (or its ID)
no_defaults – Only return existing settings and ignore defaults.
- Returns
Dict containing the settings
- property query¶
Return a query object filtering by the proxy’s module.
- set(category, name, value)¶
Set a single setting.
- Parameters
category – Category (or its ID)
name – Setting name
value – Setting value; must be JSON-serializable
- set_multi(category, items)¶
Set multiple settings at once.
- Parameters
category – Category (or its ID)
items – Dict containing the new settings