Skip to content

bulletin.doue

DOUE support is split into two layers:

  • API layer: high-level client and typed parsing models.
  • Repository layer: connector for query construction and endpoint communication.

Basic Imports

from bulletin.doue.api.client import DoueBulletinClient
from bulletin.doue.api.models import DoueOfficialAct

Client

bulletin.doue.api.client.DoueBulletinClient

Client to query EU Official Journal acts.

Source code in src/bulletin/doue/api/client.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class DoueBulletinClient:
    """Client to query EU Official Journal acts."""

    def __init__(self, endpoint: str = SPARQL_ENDPOINT, timeout: int = 300):
        self._connector = DoueConnector(endpoint=endpoint, timeout=timeout)

    def get_acts(
        self, date: str, language: str = DEFAULT_LANGUAGE, date_end: str | None = None, title_contains: str | None = None, category_type: str | None = None, institution_type: str | None = None
    ) -> list[DoueOfficialAct]:
        """Fetch Official Journal acts for a given publication date.

        Args:
            date: Publication date in ISO format (e.g. "2025-03-27").
            date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
            title_contains: Case-insensitive substring filter on title.
            category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
            institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
            language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
        Returns:
            A list of DoueOfficialAct objects.

        """
        query = self._connector.build_acts_query(date, language=language, date_end=date_end, title_contains=title_contains, category_type=category_type, institution_type=institution_type)
        response = self._connector.execute_query(query)
        return parse_acts_results(response)

    def get_acts_csv(self, date: str, date_end: str | None = None, title_contains: str | None = None, category_type: str | None = None, institution_type: str | None = None, language: str = DEFAULT_LANGUAGE) -> str:
        """
        Fetch Official Journal acts for a given date and return CSV output. Uses get_acts internally, so supports the same filters.

        Args:
            date: Publication date in ISO format (e.g. "2025-03-27").
            date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
            title_contains: Case-insensitive substring filter on title.
            category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
            institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
            language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
        Returns:
            A string containing the CSV representation of the acts.

        """
        acts = self.get_acts(date, language=language, date_end=date_end, title_contains=title_contains, category_type=category_type, institution_type=institution_type)
        return acts_to_csv(acts)

    def get_category_types(self, language: str = DEFAULT_LANGUAGE) -> list[CategoryType]:
        """Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

        Args:
            language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

        Returns:
            A list of CategoryType objects with 'code' and 'label' attributes.
        """
        query = self._connector.build_category_types_query(language=language)
        response = self._connector.execute_query(query)
        return parse_category_types_results(response)

    def get_institution_types(self, language: str = DEFAULT_LANGUAGE) -> list[InstitutionType]:
        """Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

        Args:
            language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

        Returns:
            A list of InstitutionType objects with 'code' and 'label' attributes.
        """
        query = self._connector.build_institution_types_query(language=language)
        response = self._connector.execute_query(query)
        return parse_institution_types_results(response)

get_acts(date, language=DEFAULT_LANGUAGE, date_end=None, title_contains=None, category_type=None, institution_type=None)

Fetch Official Journal acts for a given publication date.

Parameters:

Name Type Description Default
date str

Publication date in ISO format (e.g. "2025-03-27").

 required
date_end str | None

End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between date and date_end inclusive.

 None
title_contains str | None

Case-insensitive substring filter on title.

 None
category_type str | None

Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at http://publications.europa.eu/resource/authority/resource-type. Optional.

 None
institution_type str | None

Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at http://publications.europa.eu/resource/authority/corporate-body. Optional.

 None
language str

ISO Language code (default: "ENG"). Supported values are defined in LANGUAGE_CODE_MAP. Examples: "ENG", "FRA", "DEU", "SPA"...

 DEFAULT_LANGUAGE

Returns: A list of DoueOfficialAct objects.

Source code in src/bulletin/doue/api/client.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def get_acts(
    self, date: str, language: str = DEFAULT_LANGUAGE, date_end: str | None = None, title_contains: str | None = None, category_type: str | None = None, institution_type: str | None = None
) -> list[DoueOfficialAct]:
    """Fetch Official Journal acts for a given publication date.

    Args:
        date: Publication date in ISO format (e.g. "2025-03-27").
        date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
        title_contains: Case-insensitive substring filter on title.
        category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
        institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
        language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
    Returns:
        A list of DoueOfficialAct objects.

    """
    query = self._connector.build_acts_query(date, language=language, date_end=date_end, title_contains=title_contains, category_type=category_type, institution_type=institution_type)
    response = self._connector.execute_query(query)
    return parse_acts_results(response)

get_acts_csv(date, date_end=None, title_contains=None, category_type=None, institution_type=None, language=DEFAULT_LANGUAGE)

Fetch Official Journal acts for a given date and return CSV output. Uses get_acts internally, so supports the same filters.

Parameters:

Name Type Description Default
date str

Publication date in ISO format (e.g. "2025-03-27").

 required
date_end str | None

End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between date and date_end inclusive.

 None
title_contains str | None

Case-insensitive substring filter on title.

 None
category_type str | None

Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at http://publications.europa.eu/resource/authority/resource-type. Optional.

 None
institution_type str | None

Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at http://publications.europa.eu/resource/authority/corporate-body. Optional.

 None
language str

ISO Language code (default: "ENG"). Supported values are defined in LANGUAGE_CODE_MAP. Examples: "ENG", "FRA", "DEU", "SPA"...

 DEFAULT_LANGUAGE

Returns: A string containing the CSV representation of the acts.

Source code in src/bulletin/doue/api/client.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def get_acts_csv(self, date: str, date_end: str | None = None, title_contains: str | None = None, category_type: str | None = None, institution_type: str | None = None, language: str = DEFAULT_LANGUAGE) -> str:
    """
    Fetch Official Journal acts for a given date and return CSV output. Uses get_acts internally, so supports the same filters.

    Args:
        date: Publication date in ISO format (e.g. "2025-03-27").
        date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
        title_contains: Case-insensitive substring filter on title.
        category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
        institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
        language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
    Returns:
        A string containing the CSV representation of the acts.

    """
    acts = self.get_acts(date, language=language, date_end=date_end, title_contains=title_contains, category_type=category_type, institution_type=institution_type)
    return acts_to_csv(acts)

get_category_types(language=DEFAULT_LANGUAGE)

Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

Parameters:

Name Type Description Default
language str

Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

 DEFAULT_LANGUAGE

Returns:

Type Description
list[CategoryType]

A list of CategoryType objects with 'code' and 'label' attributes.
Source code in src/bulletin/doue/api/client.py 
55
56
57
58
59
60
61
62
63
64
65
66
def get_category_types(self, language: str = DEFAULT_LANGUAGE) -> list[CategoryType]:
    """Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

    Args:
        language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

    Returns:
        A list of CategoryType objects with 'code' and 'label' attributes.
    """
    query = self._connector.build_category_types_query(language=language)
    response = self._connector.execute_query(query)
    return parse_category_types_results(response)

get_institution_types(language=DEFAULT_LANGUAGE)

Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

Parameters:

Name Type Description Default
language str

Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

 DEFAULT_LANGUAGE

Returns:

Type Description
list[InstitutionType]

A list of InstitutionType objects with 'code' and 'label' attributes.
Source code in src/bulletin/doue/api/client.py 
68
69
70
71
72
73
74
75
76
77
78
79
def get_institution_types(self, language: str = DEFAULT_LANGUAGE) -> list[InstitutionType]:
    """Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

    Args:
        language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

    Returns:
        A list of InstitutionType objects with 'code' and 'label' attributes.
    """
    query = self._connector.build_institution_types_query(language=language)
    response = self._connector.execute_query(query)
    return parse_institution_types_results(response)

Models

bulletin.doue.api.models.DoueOfficialAct dataclass

Source code in src/bulletin/doue/api/models.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@dataclass
class DoueOfficialAct:
    celex_uri: str
    act_number: str | None
    title: str
    date: date
    section_code: str | None
    subsection_code: str | None
    category_code: str | None
    category_uri: str | None
    category_label: str | None
    institution_code: str | None
    institution_uri: str | None
    institution_label: str | None

    def _to_dict(self) -> dict[str, str | None]:
        """Return a serializable dict representation of the act."""
        return {
            "celex_uri": self.celex_uri,
            "act_number": self.act_number,
            "title": self.title,
            "date": self.date.isoformat(),
            "section_code": self.section_code,
            "subsection_code": self.subsection_code,
            "category_code": self.category_code,
            "category_uri": self.category_uri,
            "category_label": self.category_label,
            "institution_code": self.institution_code,
            "institution_uri": self.institution_uri,
            "institution_label": self.institution_label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> DoueOfficialAct:
        """Build a DoueOfficialAct from one SPARQL binding item."""
        return cls(
            celex_uri=_required_value(binding, "act"),
            act_number=_optional_value(binding, "actNumber"),
            title=_required_value(binding, "title"),
            date=date.fromisoformat(_required_value(binding, "date")),
            section_code=_optional_value(binding, "sectionCode"),
            subsection_code=_optional_value(binding, "subsectionCode"),
            category_code=_optional_value(binding, "categoryCode"),
            category_uri=_optional_value(binding, "categoryUri"),
            category_label=_optional_value(binding, "categoryLabel"),
            institution_code=_optional_value(binding, "institutionCode"),
            institution_uri=_optional_value(binding, "institutionUri"),
            institution_label=_optional_value(binding, "institutionLabel"),
        )

bulletin.doue.api.models.CategoryType dataclass

Represents a category type (resource type) from the authority list.

Source code in src/bulletin/doue/api/models.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@dataclass
class CategoryType:
    """Represents a category type (resource type) from the authority list."""
    code: str
    label: str

    def _to_dict(self) -> dict[str, str]:
        """Return a serializable dict representation of the category type."""
        return {
            "code": self.code,
            "label": self.label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> CategoryType:
        """Build a CategoryType from one SPARQL binding item."""
        return cls(
            code=_required_value(binding, "code"),
            label=_required_value(binding, "label"),
        )

bulletin.doue.api.models.InstitutionType dataclass

Represents an institution type from the authority list.

Source code in src/bulletin/doue/api/models.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@dataclass
class InstitutionType:
    """Represents an institution type from the authority list."""
    code: str
    label: str

    def _to_dict(self) -> dict[str, str]:
        """Return a serializable dict representation of the institution type."""
        return {
            "code": self.code,
            "label": self.label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> InstitutionType:
        """Build an InstitutionType from one SPARQL binding item."""
        return cls(
            code=_required_value(binding, "code"),
            label=_required_value(binding, "label"),
        )

Constants

bulletin.doue.constants.LANGUAGE_CODE_MAP = {'SPA': 'es', 'ENG': 'en', 'FRA': 'fr', 'DEU': 'de', 'ITA': 'it', 'POR': 'pt', 'NLD': 'nl', 'POL': 'pl', 'RON': 'ro', 'BUL': 'bg', 'CES': 'cs', 'DAN': 'da', 'ELL': 'el', 'EST': 'et', 'FIN': 'fi', 'GAE': 'ga', 'HRV': 'hr', 'HUN': 'hu', 'LIT': 'lt', 'LAV': 'lv', 'MLT': 'mt', 'SLK': 'sk', 'SLV': 'sl', 'SWE': 'sv'} module-attribute