xref: /aosp_15_r20/external/perfetto/python/generators/trace_processor_table/public.py (revision 6dbdd20afdafa5e3ca9b8809fa73465d530080dc) 
1# Copyright (C) 2022 The Android Open Source Project
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#      http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14"""Contains the public API for generating C++ tables."""
15
16from dataclasses import dataclass
17from enum import auto
18from enum import Flag as enum_Flag
19from typing import Dict
20from typing import List
21from typing import Optional
22from typing import Union
23
24
25@dataclass(frozen=True)
26class CppColumnType:
27  """
28  The type of a column on a C++ table.
29
30  See below for subclasses of this class which can be used.
31  """
32
33
34class ColumnFlag(enum_Flag):
35  """
36  Flags which should be associated to the C++ table column.
37
38  For more information on each option here, see the Column::Flag
39  enum. Keep this in sync with Column::Flag.
40  """
41  NONE = 0
42  SORTED = auto()
43  HIDDEN = auto()
44  DENSE = auto()
45  SET_ID = auto()
46
47
48@dataclass(frozen=True)
49class Column:
50  """
51  Representation of a column of a C++ table.
52
53  Attributes:
54    name: The name of the column.
55    type: The type of the column.
56    flags: Flags for the column, ColumnFlag.NONE by default.
57  """
58  name: str
59  type: CppColumnType
60  flags: ColumnFlag = ColumnFlag.NONE
61
62
63@dataclass(frozen=True)
64class ColumnDoc:
65  """
66  Documentation for the C++ table column.
67
68  Used to generate reference pages on the docs website.
69
70  Attributes:
71    doc: Freeform docstring for the column.
72    joinable: Indicates this column is joinable with a column
73    from another table. Should have the format "table.column".
74  """
75  doc: str
76  joinable: Optional[str] = None
77
78
79@dataclass(frozen=True)
80class TableDoc:
81  """
82  Documentation for the C++ table.
83
84  Used to generate reference pages on the docs website.
85
86  Attributes:
87    doc: Freeform docstring for the table.
88    group: The group of tables this table belongs to. Examples include "Tracks",
89    "Events", "ART Heap Graphs" etc: see the docs page for all the existing
90    groups.
91    columns: Documentation for each table column.
92    skip_id_and_type: Skips publishing these columns in the documentation.
93    Should only be used when these columns are not meaningful or are aliased to
94    something better.
95  """
96  doc: str
97  group: str
98  columns: Dict[str, Union[ColumnDoc, str]]
99  skip_id_and_type: bool = False
100
101
102@dataclass(frozen=True)
103class WrappingSqlView:
104  """
105  Specifies information about SQL view wrapping a table.
106
107  Useful for tables which are not exposed directly to
108  SQL but instead are wrapped with a SQL view.
109
110  Attributes:
111    view_name: The name of the SQL view exposed to SQL.
112  """
113  view_name: str
114
115
116@dataclass(frozen=True)
117class Table:
118  """
119  Representation of of a C++ table.
120
121  Attributes:
122    python_module: Path to the Python module this table is defined in. Always
123    pass __file__.
124    class_name: Name of the C++ table class.
125    sql_name: Name of the table in SQL.
126    columns: The columns in this table.
127    tabledoc: Documentation for this table. Can include documentation overrides
128    for auto-added columns (i.e. id and type) and aliases added in
129    |wrapping_sql_view|.
130    parent: The parent table for this table. All columns are inherited from the
131    specified table.
132    wrapping_sql_view: See |WrappingSqlView|.
133  """
134  python_module: str
135  class_name: str
136  sql_name: str
137  columns: List[Column]
138  parent: Optional['Table'] = None
139  tabledoc: Optional[TableDoc] = None
140  wrapping_sql_view: Optional[WrappingSqlView] = None
141
142
143@dataclass(frozen=True)
144class CppInt64(CppColumnType):
145  """Represents the int64_t C++ type."""
146
147
148@dataclass(frozen=True)
149class CppUint32(CppColumnType):
150  """Represents the uint32_t C++ type."""
151
152
153@dataclass(frozen=True)
154class CppInt32(CppColumnType):
155  """Represents the int32_t C++ type."""
156
157
158@dataclass(frozen=True)
159class CppDouble(CppColumnType):
160  """Represents the double C++ type."""
161
162
163@dataclass(frozen=True)
164class CppString(CppColumnType):
165  """Represents the StringPool::Id C++ type."""
166
167
168@dataclass(frozen=True)
169class CppOptional(CppColumnType):
170  """Represents the base::Optional C++ type."""
171  inner: CppColumnType
172
173
174@dataclass(frozen=True)
175class CppTableId(CppColumnType):
176  """Represents the Table::Id C++ type."""
177  table: Table
178
179
180@dataclass(frozen=True)
181class CppSelfTableId(CppColumnType):
182  """Represents the Id C++ type."""
183
184
185@dataclass(frozen=True)
186class Alias(CppColumnType):
187  """Represents a column which aliases another column.
188
189  Aliasing refers to re-exporting a column with a different name. This is useful
190  especially for exporting "id" columns which names which associate it to the
191  table name: e.g. exporting thread.id as thread.utid"""
192  underlying_column: str
193