API 📃

Controller

pywebchannel.Controller.Action(notify: Notify = None)

A decorator that converts a Python function into a Qt slot. The notify argument is used to emit after the function is executed. Defaults to None. If it is specified, a signal with the given name will be created and attached into the class. You don’t need to create that signal yourself. The signal will be emitted with the result of the function. EmitBy is used to specify the source of the notification. If it is set to EmitBy.Auto, the notification will be emitted automatically after the function is executed. If it is set to EmitBy.User, the notification will be emitted only if the function explicitly emits it.

Parameters:

notify (Notify, optional) – A Notify object that specifies the name and arguments of a notification signal

Returns:

A wrapper function that is a Qt slot with the same arguments and return type as the original function. The slot also handles serialization and deserialization of inputs and outputs, exception handling,and optionally emits a notification signal with the result.

References

https://doc.qt.io/qtforpython-6/tutorials/basictutorial/signals_and_slots.html

See also

Signal, Property

class pywebchannel.Controller.Controller(controllerName: str, parent: QObject | None = None)

Bases: QObject

A base class for controllers that provides common functionality.

_controllerName

A private instance attribute that stores the name of the controller.

cleanup() → None

Performs any necessary cleanup actions before the controller is destroyed.

This method can be overridden by subclasses to implement their own cleanup logic.

name() → str

Returns the name of the controller.

Returns:

A string that represents the name of the controller.

staticMetaObject = PySide6.QtCore.QMetaObject("Controller" inherits "QObject": )

class pywebchannel.Controller.Convert

Bases: object

This class provides some utility methods to convert data types between Python, Qt, and web formats.

static from_py_to_qt(argDict: Dict[str, type]) → Tuple[List[str], List[type]]

Converts a dictionary of argument names and types from Python to Qt format.

• Primitive types are kept as they are.

• List types are converted to list type.

• Pydantic types are converted to dict type.

• Other types are converted to dict type.

Returns:

Tuple[List[str], List[type]] - argument names and argument types.

static from_py_to_web(arg) → Any

Converts a Python format argument to a web format argument.

Returns:

• Primitive types are kept as they are.

• List types are recursively converted using the inner type.

• Pydantic types are converted to a dictionary using the dict() method.

• Other types are converted to a dictionary using the dict() method.

static from_py_to_web_response(result) → Dict[str, Any]

Converts a Python format result to a web format response.

• String types are wrapped in a Response object with success attribute.

• Response types are converted to a dictionary using the dict() method.

• Other types are wrapped in a Response object with data attribute.

Returns:

Dict[str, Any] - a dictionary that represents the response.

static from_web_to_py(arg, paramType) → Any

Converts a web format argument to a Python format argument according to the given parameter type.

Returns:

• Primitive types are kept as they are.

• List types are recursively converted using the inner type.

• Pydantic types are instantiated using the argument as a keyword dictionary.

• Other types are kept as they are.

class pywebchannel.Controller.EmitBy

Bases: object

A class to represent the source of a notification.

Auto = 0

User = 1

class pywebchannel.Controller.Helper

Bases: object

static infer_caller_info(stack: List[FrameInfo]) → Tuple[str, str]

A method that infers the name of the controller and the variable that called this method from the stack trace.

Parameters:

stack (List[inspect.FrameInfo]) – A list of frame information objects representing the current call stack.

Returns:

A tuple of two strings: the name of the controller and the name of the variable that called this method. If the variable name cannot be inferred, an empty string is returned as the second element of the tuple.

Return type:

Tuple[str, str]

class pywebchannel.Controller.Notify(arguments: Dict[str, type] | List[type], name: str = None, emitBy: EmitBy = 0)

Bases: object

A class to represent a notification object.

name

The name of the notification.

Type:

str

arguments

A dictionary of the arguments that the notification expects, with the argument

Type:

Dict[str, type]

name as the key and the argument type as the value.

emitBy

The source of the notification, either EmitBy.Auto or EmitBy.User.

Type:

EmitBy

The default value is EmitBy.Auto.

pywebchannel.Controller.Property(p_type: type, init_val=None, get_f=None, set_f=None) → Property

A function that creates a Qt property and a corresponding signal. The function is responsible for creating the backend variable, getter and setter functions, and the signal object related with the property.

Parameters:

• p_type (type) – The type of the property value.

• init_val – The initial value of the property. Defaults to None

• get_f (function, optional) – A custom getter function for the property. Defaults to None.

• set_f (function, optional) – A custom setter function for the property. Defaults to None.

Returns:

The prop which is a QtCore.Property object.

Raises:

Exception – If the property name cannot be inferred from the caller information

References

https://doc.qt.io/qtforpython-6/PySide6/QtCore/Property.html

See also

Signal, Action

class pywebchannel.Controller.Response(*, success: str | None = None, error: str | None = None, data: Any | None = None)

Bases: BaseModel

A Pydantic model that represents the outcome of some operation.

data: Any | None

Any Python object that stores the result of the operation. It can be of any type, such as a dict, a list, a tuple, a string, a number, etc. Pydantic will not perform any validation or conversion on this field.

error: str | None

A string that provides an error message if something went wrong during the operation. It can be None or any string value. For example, “Invalid input”, “Connection timeout”, “Database error”etc.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'data': FieldInfo(annotation=Union[Any, NoneType], required=False), 'error': FieldInfo(annotation=Union[str, NoneType], required=False), 'success': FieldInfo(annotation=Union[str, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

success: str | None

A string that indicates whether the operation was successful or not. It can be None or any string value. For example, “yes”, “no”, “ok”, “error”, etc.

pywebchannel.Controller.Signal(args: Dict[str, type] | List[type], controllerName: str = None, signalName: str = None) → Signal

A function that creates a Qt signal with the given arguments by making necessary type conversions to keep Qt and serialization process happy.

Parameters:

• args (Dict[str, type] or List[type]) – A dictionary that maps the names and types of the signal arguments.

• controllerName (str, optional) – The name of the controller that defines the signal. Defaults to None.

• signalName (str, optional) – The name of the signal. Defaults to None.

Returns:

A QtCore.Signal object with the specified arguments, name, and arguments names.

Raises:

Exception – If the controller name or signal name cannot be inferred from the caller information, or if the signal name is empty.

References

https://doc.qt.io/qtforpython-6/PySide6/QtCore/Signal.html

See also

Property, Action

class pywebchannel.Controller.Type

Bases: object

This class provides some utility methods to check the type of variable.

is_primitive(var_type

type) -> bool: Returns True if the given type is a primitive type, False otherwise.

is_list(var_type

type) -> bool: Returns True if the given type is a list type, False otherwise.

is_pydantic(var_type

type) -> bool: Returns True if the given type is a subclass of pydantic.BaseModel, False otherwise.

static is_list(var_type: type)

static is_primitive(var_type: type)

static is_pydantic(var_type: type)

primitives = (<class 'bool'>, <class 'str'>, <class 'int'>, <class 'float'>, <class 'NoneType'>)

A tuple of primitive types in Python, such as bool, str, int, float, and NoneType.

GeneratorWatcher

class pywebchannel.GeneratorWatcher.GeneratorWatcher(parent: QObject | None = None)

Bases: QFileSystemWatcher

A class that inherits from QFileSystemWatcher and watches for changes in python files.

watchTargetDirMap

A dictionary that maps the source directory to the target directory.

Type:

Dict[str, str]

addDirectory(dirPathToWatch: str, dirTargetPath: str)

A method that adds a directory to the watch list.

Parameters:

• dirPathToWatch (str) – The path of the directory to watch.

• dirTargetPath (str) – The path of the target directory to generate typescript files.

addFile(filePath: str)

A method that adds a file to the watch list.

Parameters:

filePath (str) – The path of the file to watch.

getOutputFilePath(filePath)

Get the output file path for the TypeScript file.

Parameters:

filePath (str) – The input file path for the Python file.

Returns:

The output file path for the TypeScript file.

Return type:

str

onDirectoryChanged(dirPath: str)

The slot that is triggered when a directory is changed.

Parameters:

dirPath (str) – The path of the changed directory.

onFileChanged(filePath: str)

The slot that is triggered when a file is changed.

Parameters:

filePath (str) – The path of the changed file.

staticMetaObject = PySide6.QtCore.QMetaObject("GeneratorWatcher" inherits "QFileSystemWatcher": Methods:   #9 type=Slot, signature=onDirectoryChanged(QString), parameters=QString   #10 type=Slot, signature=onFileChanged(QString), parameters=QString )

WebChannelService

class pywebchannel.WebChannelService.WebChannelService(serviceName: str, parent: QObject | None = None)

Bases: QObject

A class that inherits from QObject and provides a web channel service using QWebSocketServer and QWebChannel.

websocketServer

The QWebSocketServer object that provides the WebSocket server.

Type:

QWebSocketServer

port

The port number for the WebSocket server.

Type:

int

serviceName

The name of the web channel service.

Type:

str

clientWrapper

The WebSocketClientWrapper object that handles the WebSocket connections from the server.

Type:

WebSocketClientWrapper

channel

The QWebChannel object that manages the communication between the server and the clients.

Type:

QWebChannel

activeClientCount

The number of active WebSocket clients connected to the server.

Type:

int

isOnline() → bool

Checks if the web channel service is online by checking the status of the WebSocket server.

Returns:

True if the web channel service is online, False otherwise.

Return type:

bool

onClientConnected(transport: WebSocketTransport) → None

Connects the web channel to the WebSocket transport and increments the active client count.

This slot is invoked when the clientWrapper object emits the clientConnected signal.

Parameters:

transport (WebSocketTransport) – The WebSocketTransport object that represents the WebSocket connection.

onClientDisconnected(transport: WebSocketTransport) → None

Decrements the active client count and cleans up the controller objects if the active client count is zero.

This slot is invoked when the clientWrapper object emits the clientDisconnected signal.

Parameters:

transport (WebSocketTransport) – The WebSocketTransport object that represents the WebSocket connection.

onClosed() → None

Logs the information of closing the web channel service.

This slot is invoked when the websocketServer object emits the closed signal.

registerController(controller: Controller) → None

Registers a controller object to the web channel using the channel attribute.

Parameters:

controller (Controller) – The controller object to be registered.

start(port: int) → bool

Starts the web channel service by creating and listening to a WebSocket server at the given port.

Parameters:

port (int) – The port number for the WebSocket server.

Returns:

True if the web channel service is started successfully, False otherwise.

Return type:

bool

staticMetaObject = PySide6.QtCore.QMetaObject("WebChannelService" inherits "QObject": Methods:   #5 type=Slot, signature=onClosed()   #6 type=Slot, signature=onClientConnected(QWebChannelAbstractTransport*), parameters=QWebChannelAbstractTransport*   #7 type=Slot, signature=onClientDisconnected(QWebChannelAbstractTransport*), parameters=QWebChannelAbstractTransport* )

stop() → None

Stops the web channel service by closing and deleting the WebSocket server.

class pywebchannel.WebChannelService.WebSocketClientWrapper(server: QWebSocketServer, parent: QObject | None = None)

Bases: QObject

A class that inherits from QObject and handles the WebSocket connections from a QWebSocketServer.

server

The QWebSocketServer object that listens for WebSocket connections.

Type:

QWebSocketServer

clientConnected

The signal that is emitted when a new WebSocket connection is established.

clientDisconnected

The signal that is emitted when an existing WebSocket connection is closed.

handleNewConnection() → None

Creates a WebSocketTransport object for the next pending connection from the server and emits the clientConnected signal.

This slot is invoked when the server object emits the newConnection signal.

staticMetaObject = PySide6.QtCore.QMetaObject("WebSocketClientWrapper" inherits "QObject": Methods:   #5 type=Signal, signature=clientConnected(QWebChannelAbstractTransport*), parameters=QWebChannelAbstractTransport*   #6 type=Signal, signature=clientDisconnected(QWebChannelAbstractTransport*), parameters=QWebChannelAbstractTransport*   #7 type=Slot, signature=handleNewConnection() )

class pywebchannel.WebChannelService.WebSocketTransport(socket: QWebSocket)

Bases: QWebChannelAbstractTransport

A class that inherits from QWebChannelAbstractTransport and communicates with a QWebSocket.

socket

The QWebSocket object that handles the WebSocket connection.

Type:

QWebSocket

disconnected

The signal that is emitted when the socket is disconnected.

onSocketDisconnected() → None

Emits the disconnected signal with the self object and deletes the self object and the socket object.

This slot is invoked when the socket object emits the disconnected signal.

sendMessage(message) → None

Sends a message to the WebSocket using the socket object.

The message is converted to a QJsonDocument and then to a compact JSON string.

Parameters:

message – The message to be sent.

staticMetaObject = PySide6.QtCore.QMetaObject("WebSocketTransport" inherits "QWebChannelAbstractTransport": Methods:   #7 type=Signal, signature=disconnected(QWebChannelAbstractTransport*), parameters=QWebChannelAbstractTransport*   #8 type=Slot, signature=onSocketDisconnected()   #9 type=Slot, signature=textMessageReceived(QString), parameters=QString )

textMessageReceived(messageData: str) → None

Receives a text message from the WebSocket using the socket object and emits the messageReceived signal.

The text message is parsed as a QJsonDocument and then as a QJsonObject. If there is any error in parsing, the error is logged using the Logger object.

This slot is invoked when the socket object emits the textMessageReceived signal.

Parameters:

messageData (str) – The text message received from the WebSocket.

HttpServer

class pywebchannel.HttpServer.HttpServer(serverDir: str, port: int, parent=None)

Bases: QObject

A class that inherits from QObject and runs an HTTP server using QProcess.

process

The QProcess object that executes the HTTP server.

Type:

QProcess

port

The port number for the HTTP server.

Type:

int

serverDir

The directory path for the HTTP server.

Type:

str

onReadyReadStandardError() → None

Reads the standard error from the QProcess object and logs it using the Logger object.

This slot is invoked when the QProcess object emits the readyReadStandardError signal.

onReadyReadStandardOutput() → None

Reads the standard output from the QProcess object and logs it using the Logger object.

This slot is invoked when the QProcess object emits the readyReadStandardOutput signal.

start() → None

Starts the HTTP server using the QProcess object.

The QProcess object executes the command “python -m http.server port –directory serverDir”.

staticMetaObject = PySide6.QtCore.QMetaObject("HttpServer" inherits "QObject": Methods:   #5 type=Slot, signature=stop()   #6 type=Slot, signature=onReadyReadStandardOutput()   #7 type=Slot, signature=onReadyReadStandardError() )

stop() → None

Stops the HTTP server by killing the QProcess object.

Logs the information of stopping the HTTP server using the Logger object.

CodeAnalyzer

class pywebchannel.CodeAnalyzer.CodeAnalyzer(MetaClass)

Bases: object

A class that analyzes the code of a given class and determines its type and acceptability.

MetaClass

The class object to be analyzed.

Type:

type

_classType

The type of the class object, one of the supported types.

Type:

str

_isAcceptable

A flag indicating whether the class object is acceptable for analysis or not.

Type:

bool

classType()

Returns the type of the class object, one of the supported types.

Returns:

The type of the class object, or an empty string if not acceptable.

Return type:

str

isAcceptable()

Returns whether the class object is acceptable for analysis or not.

Returns:

True if the class object is acceptable, False otherwise.

Return type:

bool

run()

Runs the analysis on the class object and returns an interface object.

Returns:

The interface object corresponding to the class object’s type, or None if not acceptable.

class pywebchannel.CodeAnalyzer.ControllerInterface(MetaClass)

Bases: Interface

A class that represents the interface of a controller class.

A controller class is a subclass of QObject that defines properties, signals, and slots that can be used to communicate with other classes or components.

props

The properties of the controller class.

Type:

list of Property

signals

The signals of the controller class.

Type:

list of Signal

slots

The slots of the controller class.

Type:

list of Slot

classType()

Returns the type of the interface, which is SupportedTypes.Controller.

Returns:

The type of the interface.

Return type:

str

dependencies()

Returns the list of dependencies of the interface.

Dependencies are the types that are used by the properties, signals, and slots of the interface.

Returns:

The list of dependencies, without duplicates.

Return type:

list[str]

class pywebchannel.CodeAnalyzer.Interface(MetaClass)

Bases: object

A base class that represents the interface of a class.

An interface is a set of properties, signals, and slots that define the communication and functionality of a class.

MetaClass

The metaclass of the class that implements the interface.

Type:

type

name

The name of the interface.

Type:

str

objectDict

The dictionary of the meta class’s attributes and methods.

Type:

dict

staticMetaObject

The static meta-object of the meta class.

Type:

QMetaObject

props

The properties of the interface.

Type:

list of Property

signals

The signals of the interface.

Type:

list of Signal

slots

The slots of the interface.

Type:

list of Slot

classType()

Returns the type of the interface, which is “Interface”.

Returns:

The type of the interface.

Return type:

str

dependencies()

Returns the list of dependencies of the interface.

Dependencies are the types that are used by the properties, signals, and slots of the interface.

Returns:

The list of dependencies, without duplicates.

class pywebchannel.CodeAnalyzer.ModelInterface(MetaClass)

Bases: Interface

A class that represents the interface of a model class.

props

The properties of the model class.

Type:

list of Property

classType()

Returns the type of the interface, which is SupportedTypes.Model.

Returns:

The type of the interface.

Return type:

str

dependencies()

Returns the list of dependencies of the interface.

Dependencies are the types that are used by the properties of the interface.

Returns:

The list of dependencies, without duplicates.

Return type:

list[str]

class pywebchannel.CodeAnalyzer.Parameter(name: str, typeStr: str)

Bases: object

A class to represent a parameter in TypeScript.

name

The name of the parameter.

Type:

str

type

The type of the parameter in TypeScript syntax.

Type:

str

code

The code representation of the parameter.

Type:

str

convertCode() → None

Generate the code representation of the parameter.

convertType() → None

Convert the type attribute to a TypeScript compatible type.

dependencies() → list[str]

Return a list of the dependencies of the parameter type.

Returns:

A list of the types that the parameter type depends on, without brackets.

Return type:

list[str]

class pywebchannel.CodeAnalyzer.Property(name: str, typeStr: str)

Bases: object

convertCode() → None

Generate the code attribute for the property.

convertType() → None

Convert the type attribute to a TypeScript compatible type.

dependencies()

Return the dependencies of the property.

Returns:

A list of the types that the property depends on.

Return type:

list

class pywebchannel.CodeAnalyzer.Return(typeStr: str)

Bases: object

convertCode() → None

Generate the code attribute for the return type.

convertType() → None

Convert the type attribute to a TypeScript compatible type.

dependencies()

Return the dependencies of the return type.

Returns:

A list of the types that the return type depends on.

Return type:

list

class pywebchannel.CodeAnalyzer.Signal(name: str, parameters: list[Parameter], returnType: Return)

Bases: object

convertCode() → None

Generate the code attribute for the signal.

convertType() → None

Convert the type attributes of the parameters and the returnType to TypeScript compatible types.

dependencies()

Return the dependencies of the signal.

Returns:

A list of the types that the signal depends on.

Return type:

list

class pywebchannel.CodeAnalyzer.Slot(name: str, parameters: list[Parameter], returnType: Return)

Bases: object

A class to represent a slot of a TypeScript class.

name

The name of the slot.

Type:

str

parameters

A list of Parameter objects that represent the parameters of the slot function.

Type:

list[Parameter]

returnType

A Return object that represents the return type of the slot function.

Type:

Return

code

The code for the slot declaration in TypeScript.

Type:

str

convertCode() → None

Generate the code attribute for the slot.

convertType() → None

Convert the type attributes of the parameters and the returnType to TypeScript compatible types.

dependencies()

Return the dependencies of the slot.

Returns:

A list of the types that the slot depends on.

Return type:

list

class pywebchannel.CodeAnalyzer.SupportedTypes(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Controller = 'Controller'

Model = 'BaseModel'

Utils

class pywebchannel.Utils.Generator

Bases: object

A class to generate TypeScript code for interfaces.

static header()

Generate the header for the TypeScript file.

Returns:

A list of strings that represent the header lines.

Return type:

list

static imports(deps)

Generate the import statements for the TypeScript file.

Parameters:

deps (list) – A list of strings that represent the dependencies of the interfaces.

Returns:

A list of strings that represent the import statements.

Return type:

list

static interface(name: str, interface)

Generate the interface declaration for the TypeScript file.

Parameters:

• name (str) – The name of the interface.

• interface (Interface) – An Interface object that represents the interface.

Returns:

A list of strings that represent the interface declaration.

Return type:

list

class pywebchannel.Utils.Logger

Bases: object

A class to log messages with different colors and levels.

static error(message, sender='') → None

Log an error message with red color and optional sender name.

Parameters:

• message (str) – The message to log.

• sender (str) – The name of the sender of the message. Default to “”.

Returns:

None

static info(message, sender='') → None

Log an info message with green color and optional sender name.

Parameters:

• message (str) – The message to log.

• sender (str) – The name of the sender of the message. Default to “”.

Returns:

None

static status(message, sender='', override=True) → None

Log a status message with blue color and optional override flag.

Parameters:

• message (str) – The message to log.

• override (bool) – A flag to indicate whether to override the previous status message or not. Default to True.

Returns:

None

static warning(message, sender='') → None

Log a warning message with yellow color and optional sender name.

Parameters:

• message (str) – The message to log.

• sender (str) – The name of the sender of the message. Default to “”.

Returns:

None

class pywebchannel.Utils.Utils

Bases: object

A class that provides some utility methods for working with types and signatures.

VARIABLE_TYPE_MAP = {'QString': 'string', 'QVariantList': 'any[]', 'QVariantMap': 'any', 'Response': 'Response', 'any': 'any', 'bool': 'boolean', 'dict': 'any', 'double': 'number', 'float': 'number', 'int': 'number', 'list': 'any[]', 'str': 'string', 'void': 'void'}

static convertType(text) → str

Converts a Python type to a TypeScript type using the VARIABLE_TYPE_MAP.

Parameters:

text – A string that represents the Python type to be converted.

Returns:

A string that represents the TypeScript type, with the format ‘<type>[]’ for list types.

static getInheritanceTree(T: type)

Returns a dictionary that represents the inheritance tree of a given type.

Parameters:

T – A type object that represents the subclass.

Returns: A dictionary that maps the names of the base classes to their type objects, starting from the subclass to the object class.

static isList(text: str) → tuple[bool, str]

Checks if a string representation of a type is a list type.

Parameters:

text – A string that represents the type to be checked.

Returns:

A tuple of a boolean value and a string prefix. The boolean value is True if the type is a list type, and False otherwise. The string prefix is either list[ or List[ depending on the case of the type, or an empty string if the type is not a list type.

static isTypescriptPrimitive(text: str) → bool

Checks if a string representation of a type is a TypeScript primitive type.

Parameters:

text – A string that represents the type to be checked.

Returns:

A boolean value that is True if the type is a TypeScript primitive type, and False otherwise.

static parseWithInspect(f)

Parses the signature of a function using the inspect module.

Parameters:

f (function) – The function to be parsed.

Returns:

The names of the parameters of the function. paramTypes (list of str): The types of the parameters of the function, or empty strings if not annotated. returnType (str): The type of the return value of the function, or “Response” if not annotated.

Return type:

paramNames (list of str)

pp = <pprint.PrettyPrinter object>

static simplyVariableType(text: str) → str

Simplifies a str representation of a type by removing whitespace, quotation marks, and package information.

Parameters:

text – A string that represents the type to be simplified.

Returns:

A simplified string that represents the type, with the format ‘list[<type>]’ for list types.

static type_to_string(t: type)

Returns a string representation of a given type.

Parameters:

t – A type object that represents the type to be converted.

Returns:

A string that represents the type, with the format ‘list[<type>]’ for list types.