Python helpers

Python helpers#

The module plonegovbr.socialmedia.utils provides functions to build, add, merge, and read the value of a social_links field, as The social_links value describes it.

No function modifies the links it is given. A function that adds or merges links returns a new list.

Important

Assign the returned list to the field. The database does not notice a stored list changed in place.

Values#

SocialLink: The type of one link: dict[str, str | list[dict[str, str]]].
EMPTY_VALUES: The texts that count as empty in a network id or an address: "", "None", "none", and "null". Leading and trailing spaces are stripped before the comparison.
PATTERNS: The regular expressions that read a username from a profile address, by network id. It has entries for facebook and x, as Computed usernames describes.

`create_social_link`#

Returns one link to a network.

Parameter	Type	Description
`network_id`	`str`	The network, such as `x`. It is both the link's `id` and its `@id`.
`url`	`str`	The address the link points to.
`title`	`str`	The title of the link, and of its target.

Returns: A SocialLink, with its arguments stored as given.

>>> from plonegovbr.socialmedia.utils import create_social_link
>>> create_social_link("github", "https://github.com/plonegovbr", "GitHub")
{'@id': 'github', 'href': [{'@id': 'https://github.com/plonegovbr', 'title': 'GitHub'}], 'id': 'github', 'title': 'GitHub'}

`add_social_link`#

Appends a link to a network the links have no link to.

Parameter	Type	Description
`social_links`	`Sequence[Mapping]` or `None`	The links. `None` counts as no links.
`network_id`	`str`	The network, such as `x`.
`url`	`str`	The address the link points to.
`title`	`str`	The title of the link, and of its target.

Returns: A tuple of the links, as a list, and a bool that is True when the link was added. The new link is last. create_social_link builds it from network_id and url stripped of leading and trailing spaces.

The link is not added, and the links are returned as they were, in either of these cases.

A link whose id names the network, and that has a target, is already in the list. A link to the network without a target does not count.
network_id or url is empty, or one of EMPTY_VALUES.

`cleanse_social_links`#

Merges groups of links into one list, with one link per network.

Parameter	Type	Description
`base_links`	`Sequence[Mapping]` or `None`	The stored links. `None` counts as no links.
`sources`	`Iterable` of `Sequence[Mapping]` or `None`	Further groups of links, in precedence order. A group that is not a sequence is skipped. Defaults to no group.

Returns: A tuple of the merged links, as a list of dict, and a bool that is True when they differ from base_links.

The links are read in order: base_links first, then each group of sources.

The first link to each network is kept, in the order it was read.
A later link to the same network is dropped, from base_links as well as from sources.
A link that is not an object, has no id, or has no target is dropped.

Warning

cleanse_social_links drops a second link to a network from the stored links, too. To keep the stored links as they are, use add_social_link.

`link_target`#

Returns the address of a link's first target.

Parameter	Type	Description
`link`	`object`	A link.

Returns: The @id of the first object in the link's href, stripped of leading and trailing spaces. An empty string when the link is not an object, its href is not a list or does not start with an object, or that object's @id is not a string or is one of EMPTY_VALUES.

`filter_social_links`#

Returns the first link to a network that has a target.

Parameter	Type	Description
`social_links`	`list[dict]`	The links.
`network_id`	`str`	The network, such as `x`. It must equal the link's `id`.

Returns: The link itself, or None when no link to the network has a target.

`extract_username_from_profile`#

Returns the username in a profile address.

Parameter	Type	Description
`profile`	`str`	A profile address, such as `https://x.com/ploneorgbr`.
`network_id`	`str`	The network, such as `x`.

Returns: The username that the network's entry in PATTERNS reads from the address. An empty string when the network has no entry, or the address does not match it.

`extract_username_from_social_links`#

Returns the username in the first link to a network that has a target.

Parameter	Type	Description
`social_links`	`list[dict]`	The links.
`network_id`	`str`	The network, such as `x`.

Returns: The username that extract_username_from_profile reads from the target of the link filter_social_links returns. An empty string when there is no such link.

Python helpers

Contents

Python helpers#

Values#

create_social_link#

add_social_link#

cleanse_social_links#

link_target#

filter_social_links#

extract_username_from_profile#

extract_username_from_social_links#