hostray.web
Reference¶
Table of Contents
Controllers¶
-
class
hostray.web.controller.
ControllerAddon
¶ A helper class defines quick function access components
sub_classes:
-
get_localized_message
(code: Union[str, int], *args) → str¶ quick function to get localized message by
-
run_method_async
(func: Callable, *args, pool_id: str = 'default', **kwargs) → Any¶ awaitable, quick function to execute function in pool
-
log_info
(msg: str, *args, exc_info=None, extra=None, stack_info=False) → None¶ quick function to log info level message
-
log_warning
(msg: str, *args, exc_info=None, extra=None, stack_info=False) → None¶ quick function to log warning level message
-
log_error
(msg: str, *args, exc_info=None, extra=None, stack_info=False) → None¶ quick function to log error level message by
-
invoke_service_async
(service_name : str, method : str = 'get', streaming_callback : Callable = None, **kwargs) → Response¶ awaitable, quick function to send http request by service Component
-
-
class
hostray.web.controller.
RequestController
¶ Class inherits from tornado.web.RequestHandler. Please check the usage of tornado documentation
-
class
hostray.web.controller.
StreamingDownloadController
¶ Abstract class inherits from hostray.web.controller.RequestController.
-
_prepare_binary
() → bytes¶ override this awaitable function to prepare binary data for downloading
-
-
class
hostray.web.controller.
StreamingUploadController
¶ Abstract class inherits from hostray.web.controller.RequestController.
-
_on_chunk_received(self, headers, chunk, bytes_size_received):
override this function to process incoming chunk data
-
_on_data_received(self, headers, bytes_size_received):
override this function to do process after data transaction completed
-
-
class
hostray.web.controller.
StreamingFileUploadController
¶ Class inherits from hostray.web.controller.RequestController.
-
class
hostray.web.controller.
WebSocketController
¶ Class inherits from tornado.websocket.WebSocketHandler. Please check the usage of tornado documentation
Components¶
-
class
hostray.web.component.default_component.
Component
¶ Base abstract class of component
-
init
(component_manager, *arugs, **kwargs) → None¶ called when component_manager initialize component objects
-
info
() → Dict¶ return define meta information of component
-
dispose
(component_manager) → None¶ called when server stop
-
Note
Be aware of the component dependencies when server start/stop, the loaded components are sorted by the order of enums:
- server start
- DefaultComponentTypes -> OptionalComponentTypes -> Project_ComponentTypes
- server stop
- Project_ComponentTypes -> OptionalComponentTypes -> DefaultComponentTypes
-
class
hostray.web.component.default_component.
ComponentManager
¶ Contain and manage the loaded components
-
@property components -> List[Component]
return list of loaded components
-
@property info -> Dict
return info of loaded components
-
dispose
() → None¶ call dispose() of loaded components
-
boardcast
(method: str, *arugs, **kwargs) → List[Tuple[ComponentTypes, Any]]¶ invokes the non-awaitable method of stored components and return a list of returns from each component method
- method: str, method name
- *args: variable number of arguments of method
- **kwargs: keyworded, variable-length argument list of method
-
boardcast_async
(method: str, *arugs, **kwargs) → List[Tuple[ComponentTypes, Any]]¶ invokes both awaitable and non-awaitable method of stored components and return a list of returns from each component method
- method: str, method name
- *args: variable number of arguments of method
- **kwargs: keyworded, variable-length argument list of method
-
invoke
(enum_type: ComponentTypes, method: str, *arugs, **kwargs) → Any¶ execute component mehtod by giving the method name and arguments
- enum_type: ComponentTypes enum type
- method: str, method name
- *args: variable number of arguments of method
- **kwargs: keyworded, variable-length argument list of method
-
invoke_async
(enum_type: ComponentTypes, method: str, *arugs, **kwargs) → Any¶ asynchronously execute component mehtod by giving the method name and arguments
- enum_type: ComponentTypes enum type
- method: str, method name
- *args: variable number of arguments of method
- **kwargs: keyworded, variable-length argument list of method
-
set_component
(component: Component) → None¶ add or replace component instance
- component: Component instance
-
get_component
(enum_type: ComponentTypes) → Union[Component, None]¶ return stored component instance or None
- enum_type: ComponentTypes enum type
-
pick_component
(enum_types: List[ComponentTypes]) → Union[Component, None]¶ return the first founded stored component object of enum_types
- enum_type: ComponentTypes enum type
-
has_component
(enum_type: ComponentTypes) → bool¶ check whether component exists
- enum_type: ComponentTypes enum type
-
sort_components
(order_list: List[ComponentTypes]) → None¶ sort component object with ComponentTypes in order
- order_list: list of ComponentTypes
-
-
class
hostray.web.component.default_component.
LocalizationComponent
¶ -
set_language
(lang: str) → None¶ set language
- lang: key of language such as ‘en’
-
get_message
(code: str, *args) → str¶ return the message refer to ‘code’ and *args
- code: localized message code
- *args: variable number of arguments of
str
sample:
from hostray.web.controller import RequestController from hostray.web.component import DefaultComponentTypes class FooController(RequestController): async def get(self): comp = self.component_manager.get_component(DefaultComponentTypes.Localization) self.write(comp.get_message(10000))
-
-
class
hostray.web.component.default_component.
LoggerComponent
¶ -
set_default_logger_echo
(echo: bool) → None¶ enable/disable default loggers print to stdout
- echo: print log to command prompt
default_loggers = ['tornado.access', 'tornado.application', 'tornado.general', 'sqlalchemy']
-
get_logger
(name: str, sub_dir: str = '', mode: str = 'a', encoding: str = 'utf-8', echo: bool = False) → HostrayLogger¶ get HostrayLogger singleton object
- name: logger name
- sub_dir: specfied sub dir of log dir if enable logging to file
- mode: filemode
- encoding: text encoding
- echo: print log to command prompt
sample:
from hostray.web.controller import RequestController from hostray.web.component import DefaultComponentTypes class FooController(RequestController): async def get(self): comp = self.component_manager.get_component(DefaultComponentTypes.Logger) logger = comp.get_logger('some_logger')
-
-
class
hostray.web.component.default_component.
CallbackComponent
¶ -
get_callback_obj
(enum_cls: Enum) → Callbacks¶ return callback function instance
- enum_cls: class of
enum
- enum_cls: class of
-
add_callback
(callback_enum_type: Enum, callback: Callable) → None¶ registered callback function instance
- callback_enum_type: type class of
enum
- callback: callback function
- callback_enum_type: type class of
-
remove_callback
(callback_enum_type: Enum, callback: Callable) → None¶ remove callback function instance
- callback_enum_type: type class of
enum
- callback: callback function
- callback_enum_type: type class of
-
execute_callback
(callback_enum_type: Enum, *args, **kwargs) → None¶ execute registered callback functions
- callback_enum_type: type class of
enum
- *args: variable number of arguments of callback functions
- **kwargs: keyworded, variable-length argument list of callback functions
- callback_enum_type: type class of
-
execute_callback_async
(callback_enum_type: Enum, *args, **kwargs) → None¶ asynchronously execute registered callback functions
- callback_enum_type: type class of
enum
- *args: variable number of arguments of callback functions
- **kwargs: keyworded, variable-length argument list of callback functions
- callback_enum_type: type class of
-
-
class
hostray.web.component.default_component.
TaskQueueComponent
¶ -
run_method_in_queue
(func: Callable, *args, on_finish: Callable[[Any], None] = None, on_exception: Callable[[Exception], None] = None, **kwargs) → None¶ queue function and execute in differet thread
- func: function object
- *args: variable number of arguments of function object
- on_finish: callback when function finished
- on_exception: callback when function exception occurs
- **kwargs: keyworded, variable-length argument list of function object
-
Attention
run_method_in_queue() Does Not block the thread
-
class
hostray.web.component.default_component.
WorkerPoolComponent
¶ -
set_pool
(pool_id: str = 'default', worker_limit: int = 3) → None¶ creates pool if it does not exist and setup the worker maximum by ‘pool_id’
- pool_id: the id of pool
- worker_limit: maximum of workers
-
run_method
(func: Callable, *args, pool_id: str = 'default', **kwargs) → Any¶ execute func in pool with specfied ‘pool_id’
- func: function object
- *args: variable number of arguments of function object
- **kwargs: keyworded, variable-length argument list of function object
-
run_method_async
(func: Callable, *args, pool_id: str = 'default', **kwargs) → Any¶ asynchronously execute func in pool with specfied ‘pool_id’
- func: function object
- *args: variable number of arguments of function object
- **kwargs: keyworded, variable-length argument list of function object
-
Attention
run_method() Does block the thread
-
class
hostray.web.component.optional_component.
MemoryCacheComponent
¶ -
get_expired_datetime
(session_id: str) → datetime¶ Return the datetime the session id expired
- session_id: session id
-
get
(session_id: str = '', renew_lifetime: bool = False, renew_id: bool = False) → Tuple[dict, str]¶ Return tuple (cache, session_id).
- session_id: session id
- renew_lifetime: renew the expired datetime of the session_id
- renew_id: return new session_id if set to True
-
save_to_file
() → None¶ save current cache to file if the config parameter ‘save_file’ specfied
-
load_from_file
() → None¶ load file if the config parameter ‘save_file’ specfied to cache
-
clear_session
(session_id: str) → None¶ clear cache of the session_id
- session_id: session id
-
-
class
hostray.web.component.optional_component.
OrmDBComponent
¶ Managing sqlalchemy db access worker pools and execute
hostray.util.orm.OrmDBEntityAccessor
-
get_pool_obj
(db_id: str) → OrmAccessWorkerPool¶ return the db access wokrer pool object of db_id
- db_id: id of db access wokrer pool
-
get_db_settings
(db_id: str) → Dict¶ return the db setting of db_id
- db_id: id of db access wokrer pool
-
init_db_declarative_base
(db_id: str, declared_entity_base: DeclarativeMeta) → None¶ create and initialize sqlalchemy orm meta class and engine of db_id
- db_id: id of db access wokrer pool
- declared_entity_base: sqlalchemy orm meta class
-
reserve_worker
(db_id: str) → str¶ contextmanager wrapped funciton to reserve worker, return the identity
str
- db_id: id of db access wokrer pool
-
reserve_worker_async
(db_id: str) → str¶ asynccontextmanager wrapped funciton to reserve worker, return the identity
str
- db_id: id of db access wokrer pool
-
reset_session
(db_id: str, force_reconnect: bool = False) → None¶ reset db session and connection
- db_id: id of db access wokrer pool
- force_reconnect: ignore minimum interval ‘connection_refresh’ and reset db session and connection
-
reset_session_async
(db_id: str, force_reconnect: bool = False) → None¶ asynchronously reset db session and connection
- db_id: id of db access wokrer pool
- force_reconnect: ignore minimum interval ‘connection_refresh’ and reset db session and connection
-
run_accessor
(db_id: str, accessor_func: Callable, *args, identity: str = None, **kwargs) → Any¶ execute function of
hostray.util.orm.OrmDBEntityAccessor
- db_id: id of db access wokrer pool
- accessor_func: function of
hostray.util.orm.OrmDBEntityAccessor
- *args: variable number of arguments of accessor function object
- **kwargs: keyworded, variable-length argument list of accessor function object
-
run_accessor_async
(db_id: str, accessor_func: Callable, *args, identity: str = None, **kwargs) → Any¶ asynchronously execute function of
hostray.util.orm.OrmDBEntityAccessor
- db_id: id of db access wokrer pool
- accessor_func: function of
hostray.util.orm.OrmDBEntityAccessor
- *args: variable number of arguments of accessor function object
- **kwargs: keyworded, variable-length argument list of accessor function object
-
-
class
hostray.web.component.optional_component.
ServicesComponent
¶ -
invoke
(service_name: str, method='get', streaming_callback: Callable = None, **kwargs) → requests.Response¶ seed http request to config specfied service_name and return
requests.Response
object- service_name: config specfied service_name
- method: http methods
['get', 'post', 'patch', 'put', 'delete', 'option']
- streaming_callback: streaming operation callback function, check Reference
- **kwargs: keyworded, variable-length argument list of http method parameters
-
invoke_async
(service_name: str, method='get', streaming_callback: Callable = None, **kwargs) → requests.Response¶ asynchronously seed http request to config specfied service_name and return
requests.Response
object- service_name: config specfied service_name
- method: http methods
['get', 'post', 'patch', 'put', 'delete', 'option']
- streaming_callback: streaming operation callback function, check Reference
- **kwargs: keyworded, variable-length argument list of http method parameters
-
Configuration Validator¶
-
class
hostray.web.config_validator.
ConfigBaseElementMeta
¶ base config element metaclass
-
set_cls_parameters
(*cls_parameters) → None¶ @classmethod, set the sub class elements
- *parameters: variable number of arguments of ConfigBaseElementMeta
-
get_cls_parameter
(key_routes, delimeter=".") → type¶ @classmethod, get the sub class elements
- key_routes: route in
str
- delimeter: delimeter of route.split()
- key_routes: route in
-
get_parameter
(key_routes: str, delimeter: str = '.')¶ return parameter of specfied key_routes
- key_routes: route in
str
- delimeter: delimeter of route.split()
- key_routes: route in
-
-
class
hostray.web.config_validator.
ConfigContainerMeta
¶ Configration validation element metaclass contain sub elements
-
__new__
(name: str, required: bool, *parameters) → type¶ - name: name of type
- required: specfied is this element is required in config
- *parameters: variable number of arguments of ConfigBaseElementMeta
-
copy
(name) → type¶ - name: name of copied type
-
-
class
hostray.web.config_validator.
ConfigElementMeta
¶ Configration validation element metaclass store parameters
-
__new__
(name: str, parameter_type: Any, required: bool) → type¶ - name: name of type
- parameter_type: variable type such
str, int, float
- required: specfied is this element is required in config
-
copy
(name) → type¶ - name: name of copied type
-
-
class
hostray.web.config_validator.
ConfigScalableContainerMeta
¶ scalable configration validation element metaclass contain sub elements metaclass
-
__new__
(parameter_type: Union[str, int], *parameters) → type¶ - parameter_type: variable type such
str, int, float
- *parameters: variable number of arguments of ConfigBaseElementMeta
- parameter_type: variable type such
-
copy
(name) → type¶ - name: name of copied type
-
-
class
hostray.web.config_validator.
ConfigScalableElementMeta
¶ scalable configration validation element metaclass
-
__new__
(element_type: Union[str, int], parameter_type: Any) → type¶ - element_type: scalable key variable type such as
str, int, float
- parameter_type: variable type such as
str, int, float
- element_type: scalable key variable type such as
-
copy
(name) → type¶ - name: name of copied type
-
-
class
hostray.web.config_validator.
ConfigSwitchableElementMeta
¶ switchable configration validation element metaclass
-
__new__
(name: str, parameter_type: Any, required: bool, *parameters) → type¶ - name: name of type
- parameter_type: variable type
- required: specfied is this element is required in config
- *parameters: variable number of arguments of ConfigBaseElementMeta
-
copy
(name) → type¶ - name: name of copied type
-
-
class
hostray.web.config_validator.
HostrayWebConfigValidator
¶ default validator to validate
server_config.yaml
.
-
class
hostray.web.config_validator.
HostrayWebConfigControllerValidator
¶ default validator to validate the controller block of
server_config.yaml
.
-
class
hostray.web.config_validator.
HostrayWebConfigComponentValidator
¶ default validator to validate the component block of
server_config.yaml
.