Coverage for pyngrok/conf.py: 96.67%

30 statements  

« prev     ^ index     » next       coverage.py v7.3.1, created at 2023-09-13 02:08 +0000

1import os 

2 

3from pyngrok.installer import get_ngrok_bin 

4 

5__author__ = "Alex Laird" 

6__copyright__ = "Copyright 2023, Alex Laird" 

7__version__ = "6.1.0" 

8 

9BIN_DIR = os.path.normpath(os.path.join(os.path.abspath(os.path.dirname(__file__)), "bin")) 

10DEFAULT_NGROK_PATH = os.path.join(BIN_DIR, get_ngrok_bin()) 

11DEFAULT_CONFIG_PATH = None 

12 

13DEFAULT_NGROK_CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".ngrok2", "ngrok.yml") 

14 

15_default_pyngrok_config = None 

16 

17 

18class PyngrokConfig: 

19 """ 

20 An object containing ``pyngrok``'s configuration for interacting with the ``ngrok`` binary. All values are 

21 optional when it is instantiated, and default values will be used for parameters not passed. 

22 

23 Use :func:`~pyngrok.conf.get_default` and :func:`~pyngrok.conf.set_default` to interact with the default 

24 ``pyngrok_config``, or pass another instance of this object as the ``pyngrok_config`` keyword arg to most 

25 methods in the :mod:`~pyngrok.ngrok` module to override the default. 

26 

27 .. code-block:: python 

28 

29 from pyngrok import conf, ngrok 

30 

31 # Here we update the entire default config 

32 pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok") 

33 conf.set_default(pyngrok_config) 

34 

35 # Here we update just one variable in the default config 

36 conf.get_default().ngrok_path = "/usr/local/bin/ngrok" 

37 

38 # Here we leave the default config as-is and pass an override 

39 pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok") 

40 ngrok.connect(pyngrok_config=pyngrok_config) 

41 

42 :var ngrok_path: The path to the ``ngrok`` binary, defaults to the value in 

43 `conf.DEFAULT_NGROK_PATH <index.html#config-file>`_ 

44 :vartype ngrok_path: str 

45 :var config_path: The path to the ``ngrok`` config, defaults to ``None`` and ``ngrok`` manages it. 

46 :vartype config_path: str 

47 :var auth_token: A ``ngrok`` authtoken to pass to commands (overrides what is in the config). 

48 :vartype auth_token: str 

49 :var region: The region in which ``ngrok`` should start. 

50 :vartype region: str 

51 :var monitor_thread: Whether ``ngrok`` should continue to be monitored (for logs, etc.) after startup 

52 is complete. 

53 :vartype monitor_thread: bool 

54 :var log_event_callback: A callback that will be invoked each time ``ngrok`` emits a log. The function should take 

55 one argument of type :py:class:`str`. ``monitor_thread`` must be set to ``True`` or the function will stop being called 

56 after ``ngrok`` finishes starting. 

57 :vartype log_event_callback: types.FunctionType 

58 :var startup_timeout: The max number of seconds to wait for ``ngrok`` to start before timing out. 

59 :vartype startup_timeout: int 

60 :var max_logs: The max number of logs to store in :class:`~pyngrok.process.NgrokProcess`'s ``logs`` variable. 

61 :vartype max_logs: int 

62 :var request_timeout: The max timeout when making requests to ``ngrok``'s API. 

63 :vartype request_timeout: float 

64 :var start_new_session: Passed to :py:class:`subprocess.Popen` when launching ``ngrok``. (Python 3 and POSIX only) 

65 :vartype start_new_session: bool 

66 :var ngrok_version: The major version of ``ngrok`` installed. 

67 :vartype ngrok_version: str 

68 :var api_key: A ``ngrok`` API key. 

69 :vartype api_key: str 

70 """ 

71 

72 def __init__(self, 

73 ngrok_path=None, 

74 config_path=None, 

75 auth_token=None, 

76 region=None, 

77 monitor_thread=True, 

78 log_event_callback=None, 

79 startup_timeout=15, 

80 max_logs=100, 

81 request_timeout=4, 

82 start_new_session=False, 

83 ngrok_version="v3", 

84 api_key=None): 

85 self.ngrok_path = DEFAULT_NGROK_PATH if ngrok_path is None else ngrok_path 

86 self.config_path = DEFAULT_CONFIG_PATH if config_path is None else config_path 

87 self.auth_token = auth_token 

88 self.region = region 

89 self.monitor_thread = monitor_thread 

90 self.log_event_callback = log_event_callback 

91 self.startup_timeout = startup_timeout 

92 self.max_logs = max_logs 

93 self.request_timeout = request_timeout 

94 self.start_new_session = start_new_session 

95 self.ngrok_version = ngrok_version 

96 self.api_key = api_key 

97 

98 

99def get_default(): 

100 """ 

101 Get the default config to be used with methods in the :mod:`~pyngrok.ngrok` module. To override the 

102 default individually, the ``pyngrok_config`` keyword arg can also be passed to most of these methods, 

103 or set a new default config with :func:`~pyngrok.conf.set_default`. 

104 

105 :return: The default ``pyngrok_config``. 

106 :rtype: PyngrokConfig 

107 """ 

108 if _default_pyngrok_config is None: 

109 set_default(PyngrokConfig()) 

110 

111 return _default_pyngrok_config 

112 

113 

114def set_default(pyngrok_config): 

115 """ 

116 Set a new default config to be used with methods in the :mod:`~pyngrok.ngrok` module. To override the 

117 default individually, the ``pyngrok_config`` keyword arg can also be passed to most of these methods. 

118 

119 :param pyngrok_config: The new ``pyngrok_config`` to be used by default. 

120 :type pyngrok_config: PyngrokConfig 

121 """ 

122 global _default_pyngrok_config 

123 

124 _default_pyngrok_config = pyngrok_config