You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

1856 line
55 KiB

  1. # Copyright (c) 2015, Frappe Technologies Pvt. Ltd. and Contributors
  2. # License: MIT. See LICENSE
  3. """
  4. Frappe - Low Code Open Source Framework in Python and JS
  5. Frappe, pronounced fra-pay, is a full stack, batteries-included, web
  6. framework written in Python and Javascript with MariaDB as the database.
  7. It is the framework which powers ERPNext. It is pretty generic and can
  8. be used to build database driven apps.
  9. Read the documentation: https://frappeframework.com/docs
  10. """
  11. import os, warnings
  12. _dev_server = os.environ.get('DEV_SERVER', False)
  13. if _dev_server:
  14. warnings.simplefilter('always', DeprecationWarning)
  15. warnings.simplefilter('always', PendingDeprecationWarning)
  16. from werkzeug.local import Local, release_local
  17. import sys, importlib, inspect, json
  18. import typing
  19. import click
  20. # Local application imports
  21. from .exceptions import *
  22. from .utils.jinja import (get_jenv, get_template, render_template, get_email_from_template, get_jloader)
  23. from .utils.lazy_loader import lazy_import
  24. from frappe.query_builder import get_query_builder, patch_query_execute
  25. # Lazy imports
  26. faker = lazy_import('faker')
  27. __version__ = '14.0.0-dev'
  28. __title__ = "Frappe Framework"
  29. local = Local()
  30. controllers = {}
  31. class _dict(dict):
  32. """dict like object that exposes keys as attributes"""
  33. def __getattr__(self, key):
  34. ret = self.get(key)
  35. if not ret and key.startswith("__"):
  36. raise AttributeError()
  37. return ret
  38. def __setattr__(self, key, value):
  39. self[key] = value
  40. def __getstate__(self):
  41. return self
  42. def __setstate__(self, d):
  43. self.update(d)
  44. def update(self, d):
  45. """update and return self -- the missing dict feature in python"""
  46. super(_dict, self).update(d)
  47. return self
  48. def copy(self):
  49. return _dict(dict(self).copy())
  50. def _(msg, lang=None, context=None):
  51. """Returns translated string in current lang, if exists.
  52. Usage:
  53. _('Change')
  54. _('Change', context='Coins')
  55. """
  56. from frappe.translate import get_full_dict
  57. from frappe.utils import strip_html_tags, is_html
  58. if not hasattr(local, 'lang'):
  59. local.lang = lang or 'en'
  60. if not lang:
  61. lang = local.lang
  62. non_translated_string = msg
  63. if is_html(msg):
  64. msg = strip_html_tags(msg)
  65. # msg should always be unicode
  66. msg = as_unicode(msg).strip()
  67. translated_string = ''
  68. if context:
  69. string_key = '{msg}:{context}'.format(msg=msg, context=context)
  70. translated_string = get_full_dict(lang).get(string_key)
  71. if not translated_string:
  72. translated_string = get_full_dict(lang).get(msg)
  73. # return lang_full_dict according to lang passed parameter
  74. return translated_string or non_translated_string
  75. def as_unicode(text, encoding='utf-8'):
  76. '''Convert to unicode if required'''
  77. if isinstance(text, str):
  78. return text
  79. elif text==None:
  80. return ''
  81. elif isinstance(text, bytes):
  82. return str(text, encoding)
  83. else:
  84. return str(text)
  85. def get_lang_dict(fortype, name=None):
  86. """Returns the translated language dict for the given type and name.
  87. :param fortype: must be one of `doctype`, `page`, `report`, `include`, `jsfile`, `boot`
  88. :param name: name of the document for which assets are to be returned."""
  89. from frappe.translate import get_dict
  90. return get_dict(fortype, name)
  91. def set_user_lang(user, user_language=None):
  92. """Guess and set user language for the session. `frappe.local.lang`"""
  93. from frappe.translate import get_user_lang
  94. local.lang = get_user_lang(user)
  95. # local-globals
  96. db = local("db")
  97. qb = local("qb")
  98. conf = local("conf")
  99. form = form_dict = local("form_dict")
  100. request = local("request")
  101. response = local("response")
  102. session = local("session")
  103. user = local("user")
  104. flags = local("flags")
  105. error_log = local("error_log")
  106. debug_log = local("debug_log")
  107. message_log = local("message_log")
  108. lang = local("lang")
  109. # This if block is never executed when running the code. It is only used for
  110. # telling static code analyzer where to find dynamically defined attributes.
  111. if typing.TYPE_CHECKING:
  112. from frappe.database.mariadb.database import MariaDBDatabase
  113. from frappe.database.postgres.database import PostgresDatabase
  114. from pypika import Query
  115. db: typing.Union[MariaDBDatabase, PostgresDatabase]
  116. qb: Query
  117. # end: static analysis hack
  118. def init(site, sites_path=None, new_site=False):
  119. """Initialize frappe for the current site. Reset thread locals `frappe.local`"""
  120. if getattr(local, "initialised", None):
  121. return
  122. if not sites_path:
  123. sites_path = '.'
  124. local.error_log = []
  125. local.message_log = []
  126. local.debug_log = []
  127. local.realtime_log = []
  128. local.flags = _dict({
  129. "currently_saving": [],
  130. "redirect_location": "",
  131. "in_install_db": False,
  132. "in_install_app": False,
  133. "in_import": False,
  134. "in_test": False,
  135. "mute_messages": False,
  136. "ignore_links": False,
  137. "mute_emails": False,
  138. "has_dataurl": False,
  139. "new_site": new_site
  140. })
  141. local.rollback_observers = []
  142. local.before_commit = []
  143. local.test_objects = {}
  144. local.site = site
  145. local.sites_path = sites_path
  146. local.site_path = os.path.join(sites_path, site)
  147. local.all_apps = None
  148. local.request_ip = None
  149. local.response = _dict({"docs":[]})
  150. local.task_id = None
  151. local.conf = _dict(get_site_config())
  152. local.lang = local.conf.lang or "en"
  153. local.lang_full_dict = None
  154. local.module_app = None
  155. local.app_modules = None
  156. local.system_settings = _dict()
  157. local.user = None
  158. local.user_perms = None
  159. local.session = None
  160. local.role_permissions = {}
  161. local.valid_columns = {}
  162. local.new_doc_templates = {}
  163. local.link_count = {}
  164. local.jenv = None
  165. local.jloader =None
  166. local.cache = {}
  167. local.document_cache = {}
  168. local.meta_cache = {}
  169. local.form_dict = _dict()
  170. local.session = _dict()
  171. local.dev_server = _dev_server
  172. local.qb = get_query_builder(local.conf.db_type or "mariadb")
  173. setup_module_map()
  174. patch_query_execute()
  175. local.initialised = True
  176. def connect(site=None, db_name=None, set_admin_as_user=True):
  177. """Connect to site database instance.
  178. :param site: If site is given, calls `frappe.init`.
  179. :param db_name: Optional. Will use from `site_config.json`.
  180. :param set_admin_as_user: Set Administrator as current user.
  181. """
  182. from frappe.database import get_db
  183. if site:
  184. init(site)
  185. local.db = get_db(user=db_name or local.conf.db_name)
  186. if set_admin_as_user:
  187. set_user("Administrator")
  188. def connect_replica():
  189. from frappe.database import get_db
  190. user = local.conf.db_name
  191. password = local.conf.db_password
  192. port = local.conf.replica_db_port
  193. if local.conf.different_credentials_for_replica:
  194. user = local.conf.replica_db_name
  195. password = local.conf.replica_db_password
  196. local.replica_db = get_db(host=local.conf.replica_host, user=user, password=password, port=port)
  197. # swap db connections
  198. local.primary_db = local.db
  199. local.db = local.replica_db
  200. def get_site_config(sites_path=None, site_path=None):
  201. """Returns `site_config.json` combined with `sites/common_site_config.json`.
  202. `site_config` is a set of site wide settings like database name, password, email etc."""
  203. config = {}
  204. sites_path = sites_path or getattr(local, "sites_path", None)
  205. site_path = site_path or getattr(local, "site_path", None)
  206. if sites_path:
  207. common_site_config = os.path.join(sites_path, "common_site_config.json")
  208. if os.path.exists(common_site_config):
  209. try:
  210. config.update(get_file_json(common_site_config))
  211. except Exception as error:
  212. click.secho("common_site_config.json is invalid", fg="red")
  213. print(error)
  214. if site_path:
  215. site_config = os.path.join(site_path, "site_config.json")
  216. if os.path.exists(site_config):
  217. try:
  218. config.update(get_file_json(site_config))
  219. except Exception as error:
  220. click.secho("{0}/site_config.json is invalid".format(local.site), fg="red")
  221. print(error)
  222. elif local.site and not local.flags.new_site:
  223. raise IncorrectSitePath("{0} does not exist".format(local.site))
  224. return _dict(config)
  225. def get_conf(site=None):
  226. if hasattr(local, 'conf'):
  227. return local.conf
  228. else:
  229. # if no site, get from common_site_config.json
  230. with init_site(site):
  231. return local.conf
  232. class init_site:
  233. def __init__(self, site=None):
  234. '''If site==None, initialize it for empty site ('') to load common_site_config.json'''
  235. self.site = site or ''
  236. def __enter__(self):
  237. init(self.site)
  238. return local
  239. def __exit__(self, type, value, traceback):
  240. destroy()
  241. def destroy():
  242. """Closes connection and releases werkzeug local."""
  243. if db:
  244. db.close()
  245. release_local(local)
  246. # memcache
  247. redis_server = None
  248. def cache():
  249. """Returns redis connection."""
  250. global redis_server
  251. if not redis_server:
  252. from frappe.utils.redis_wrapper import RedisWrapper
  253. redis_server = RedisWrapper.from_url(conf.get('redis_cache')
  254. or "redis://localhost:11311")
  255. return redis_server
  256. def get_traceback():
  257. """Returns error traceback."""
  258. from frappe.utils import get_traceback
  259. return get_traceback()
  260. def errprint(msg):
  261. """Log error. This is sent back as `exc` in response.
  262. :param msg: Message."""
  263. msg = as_unicode(msg)
  264. if not request or (not "cmd" in local.form_dict) or conf.developer_mode:
  265. print(msg)
  266. error_log.append({"exc": msg})
  267. def print_sql(enable=True):
  268. return cache().set_value('flag_print_sql', enable)
  269. def log(msg):
  270. """Add to `debug_log`.
  271. :param msg: Message."""
  272. if not request:
  273. if conf.get("logging") or False:
  274. print(repr(msg))
  275. debug_log.append(as_unicode(msg))
  276. def msgprint(msg, title=None, raise_exception=0, as_table=False, as_list=False, indicator=None, alert=False, primary_action=None, is_minimizable=None, wide=None):
  277. """Print a message to the user (via HTTP response).
  278. Messages are sent in the `__server_messages` property in the
  279. response JSON and shown in a pop-up / modal.
  280. :param msg: Message.
  281. :param title: [optional] Message title.
  282. :param raise_exception: [optional] Raise given exception and show message.
  283. :param as_table: [optional] If `msg` is a list of lists, render as HTML table.
  284. :param as_list: [optional] If `msg` is a list, render as un-ordered list.
  285. :param primary_action: [optional] Bind a primary server/client side action.
  286. :param is_minimizable: [optional] Allow users to minimize the modal
  287. :param wide: [optional] Show wide modal
  288. """
  289. from frappe.utils import strip_html_tags
  290. msg = safe_decode(msg)
  291. out = _dict(message=msg)
  292. def _raise_exception():
  293. if raise_exception:
  294. if flags.rollback_on_exception:
  295. db.rollback()
  296. import inspect
  297. if inspect.isclass(raise_exception) and issubclass(raise_exception, Exception):
  298. raise raise_exception(msg)
  299. else:
  300. raise ValidationError(msg)
  301. if flags.mute_messages:
  302. _raise_exception()
  303. return
  304. if as_table and type(msg) in (list, tuple):
  305. out.as_table = 1
  306. if as_list and type(msg) in (list, tuple) and len(msg) > 1:
  307. out.as_list = 1
  308. if flags.print_messages and out.message:
  309. print(f"Message: {strip_html_tags(out.message)}")
  310. if title:
  311. out.title = title
  312. if not indicator and raise_exception:
  313. indicator = 'red'
  314. if indicator:
  315. out.indicator = indicator
  316. if is_minimizable:
  317. out.is_minimizable = is_minimizable
  318. if alert:
  319. out.alert = 1
  320. if raise_exception:
  321. out.raise_exception = 1
  322. if primary_action:
  323. out.primary_action = primary_action
  324. if wide:
  325. out.wide = wide
  326. message_log.append(json.dumps(out))
  327. if raise_exception and hasattr(raise_exception, '__name__'):
  328. local.response['exc_type'] = raise_exception.__name__
  329. _raise_exception()
  330. def clear_messages():
  331. local.message_log = []
  332. def get_message_log():
  333. log = []
  334. for msg_out in local.message_log:
  335. log.append(json.loads(msg_out))
  336. return log
  337. def clear_last_message():
  338. if len(local.message_log) > 0:
  339. local.message_log = local.message_log[:-1]
  340. def throw(msg, exc=ValidationError, title=None, is_minimizable=None, wide=None, as_list=False):
  341. """Throw execption and show message (`msgprint`).
  342. :param msg: Message.
  343. :param exc: Exception class. Default `frappe.ValidationError`"""
  344. msgprint(msg, raise_exception=exc, title=title, indicator='red', is_minimizable=is_minimizable, wide=wide, as_list=as_list)
  345. def emit_js(js, user=False, **kwargs):
  346. if user == False:
  347. user = session.user
  348. publish_realtime('eval_js', js, user=user, **kwargs)
  349. def create_folder(path, with_init=False):
  350. """Create a folder in the given path and add an `__init__.py` file (optional).
  351. :param path: Folder path.
  352. :param with_init: Create `__init__.py` in the new folder."""
  353. from frappe.utils import touch_file
  354. if not os.path.exists(path):
  355. os.makedirs(path)
  356. if with_init:
  357. touch_file(os.path.join(path, "__init__.py"))
  358. def set_user(username):
  359. """Set current user.
  360. :param username: **User** name to set as current user."""
  361. local.session.user = username
  362. local.session.sid = username
  363. local.cache = {}
  364. local.form_dict = _dict()
  365. local.jenv = None
  366. local.session.data = _dict()
  367. local.role_permissions = {}
  368. local.new_doc_templates = {}
  369. local.user_perms = None
  370. def get_user():
  371. from frappe.utils.user import UserPermissions
  372. if not local.user_perms:
  373. local.user_perms = UserPermissions(local.session.user)
  374. return local.user_perms
  375. def get_roles(username=None):
  376. """Returns roles of current user."""
  377. if not local.session:
  378. return ["Guest"]
  379. import frappe.permissions
  380. return frappe.permissions.get_roles(username or local.session.user)
  381. def get_request_header(key, default=None):
  382. """Return HTTP request header.
  383. :param key: HTTP header key.
  384. :param default: Default value."""
  385. return request.headers.get(key, default)
  386. def sendmail(recipients=[], sender="", subject="No Subject", message="No Message",
  387. as_markdown=False, delayed=True, reference_doctype=None, reference_name=None,
  388. unsubscribe_method=None, unsubscribe_params=None, unsubscribe_message=None, add_unsubscribe_link=1,
  389. attachments=None, content=None, doctype=None, name=None, reply_to=None, queue_separately=False,
  390. cc=[], bcc=[], message_id=None, in_reply_to=None, send_after=None, expose_recipients=None,
  391. send_priority=1, communication=None, retry=1, now=None, read_receipt=None, is_notification=False,
  392. inline_images=None, template=None, args=None, header=None, print_letterhead=False, with_container=False):
  393. """Send email using user's default **Email Account** or global default **Email Account**.
  394. :param recipients: List of recipients.
  395. :param sender: Email sender. Default is current user or default outgoing account.
  396. :param subject: Email Subject.
  397. :param message: (or `content`) Email Content.
  398. :param as_markdown: Convert content markdown to HTML.
  399. :param delayed: Send via scheduled email sender **Email Queue**. Don't send immediately. Default is true
  400. :param send_priority: Priority for Email Queue, default 1.
  401. :param reference_doctype: (or `doctype`) Append as communication to this DocType.
  402. :param reference_name: (or `name`) Append as communication to this document name.
  403. :param unsubscribe_method: Unsubscribe url with options email, doctype, name. e.g. `/api/method/unsubscribe`
  404. :param unsubscribe_params: Unsubscribe paramaters to be loaded on the unsubscribe_method [optional] (dict).
  405. :param attachments: List of attachments.
  406. :param reply_to: Reply-To Email Address.
  407. :param message_id: Used for threading. If a reply is received to this email, Message-Id is sent back as In-Reply-To in received email.
  408. :param in_reply_to: Used to send the Message-Id of a received email back as In-Reply-To.
  409. :param send_after: Send after the given datetime.
  410. :param expose_recipients: Display all recipients in the footer message - "This email was sent to"
  411. :param communication: Communication link to be set in Email Queue record
  412. :param inline_images: List of inline images as {"filename", "filecontent"}. All src properties will be replaced with random Content-Id
  413. :param template: Name of html template from templates/emails folder
  414. :param args: Arguments for rendering the template
  415. :param header: Append header in email
  416. :param with_container: Wraps email inside a styled container
  417. """
  418. text_content = None
  419. if template:
  420. message, text_content = get_email_from_template(template, args)
  421. message = content or message
  422. if as_markdown:
  423. from frappe.utils import md_to_html
  424. message = md_to_html(message)
  425. if not delayed:
  426. now = True
  427. from frappe.email.doctype.email_queue.email_queue import QueueBuilder
  428. builder = QueueBuilder(recipients=recipients, sender=sender,
  429. subject=subject, message=message, text_content=text_content,
  430. reference_doctype = doctype or reference_doctype, reference_name = name or reference_name, add_unsubscribe_link=add_unsubscribe_link,
  431. unsubscribe_method=unsubscribe_method, unsubscribe_params=unsubscribe_params, unsubscribe_message=unsubscribe_message,
  432. attachments=attachments, reply_to=reply_to, cc=cc, bcc=bcc, message_id=message_id, in_reply_to=in_reply_to,
  433. send_after=send_after, expose_recipients=expose_recipients, send_priority=send_priority, queue_separately=queue_separately,
  434. communication=communication, read_receipt=read_receipt, is_notification=is_notification,
  435. inline_images=inline_images, header=header, print_letterhead=print_letterhead, with_container=with_container)
  436. # build email queue and send the email if send_now is True.
  437. builder.process(send_now=now)
  438. whitelisted = []
  439. guest_methods = []
  440. xss_safe_methods = []
  441. allowed_http_methods_for_whitelisted_func = {}
  442. def whitelist(allow_guest=False, xss_safe=False, methods=None):
  443. """
  444. Decorator for whitelisting a function and making it accessible via HTTP.
  445. Standard request will be `/api/method/[path.to.method]`
  446. :param allow_guest: Allow non logged-in user to access this method.
  447. :param methods: Allowed http method to access the method.
  448. Use as:
  449. @frappe.whitelist()
  450. def myfunc(param1, param2):
  451. pass
  452. """
  453. if not methods:
  454. methods = ['GET', 'POST', 'PUT', 'DELETE']
  455. def innerfn(fn):
  456. global whitelisted, guest_methods, xss_safe_methods, allowed_http_methods_for_whitelisted_func
  457. # get function from the unbound / bound method
  458. # this is needed because functions can be compared, but not methods
  459. method = None
  460. if hasattr(fn, '__func__'):
  461. method = fn
  462. fn = method.__func__
  463. whitelisted.append(fn)
  464. allowed_http_methods_for_whitelisted_func[fn] = methods
  465. if allow_guest:
  466. guest_methods.append(fn)
  467. if xss_safe:
  468. xss_safe_methods.append(fn)
  469. return method or fn
  470. return innerfn
  471. def is_whitelisted(method):
  472. from frappe.utils import sanitize_html
  473. is_guest = session['user'] == 'Guest'
  474. if method not in whitelisted or is_guest and method not in guest_methods:
  475. throw(_("Not permitted"), PermissionError)
  476. if is_guest and method not in xss_safe_methods:
  477. # strictly sanitize form_dict
  478. # escapes html characters like <> except for predefined tags like a, b, ul etc.
  479. for key, value in form_dict.items():
  480. if isinstance(value, str):
  481. form_dict[key] = sanitize_html(value)
  482. def read_only():
  483. def innfn(fn):
  484. def wrapper_fn(*args, **kwargs):
  485. if conf.read_from_replica:
  486. connect_replica()
  487. try:
  488. retval = fn(*args, **get_newargs(fn, kwargs))
  489. finally:
  490. if local and hasattr(local, 'primary_db'):
  491. local.db.close()
  492. local.db = local.primary_db
  493. return retval
  494. return wrapper_fn
  495. return innfn
  496. def write_only():
  497. # if replica connection exists, we have to replace it momentarily with the primary connection
  498. def innfn(fn):
  499. def wrapper_fn(*args, **kwargs):
  500. primary_db = getattr(local, "primary_db", None)
  501. replica_db = getattr(local, "replica_db", None)
  502. in_read_only = getattr(local, "db", None) != primary_db
  503. # switch to primary connection
  504. if in_read_only and primary_db:
  505. local.db = local.primary_db
  506. try:
  507. retval = fn(*args, **get_newargs(fn, kwargs))
  508. finally:
  509. # switch back to replica connection
  510. if in_read_only and replica_db:
  511. local.db = replica_db
  512. return retval
  513. return wrapper_fn
  514. return innfn
  515. def only_for(roles, message=False):
  516. """Raise `frappe.PermissionError` if the user does not have any of the given **Roles**.
  517. :param roles: List of roles to check."""
  518. if local.flags.in_test:
  519. return
  520. if not isinstance(roles, (tuple, list)):
  521. roles = (roles,)
  522. roles = set(roles)
  523. myroles = set(get_roles())
  524. if not roles.intersection(myroles):
  525. if message:
  526. msgprint(_('This action is only allowed for {}').format(bold(', '.join(roles))), _('Not Permitted'))
  527. raise PermissionError
  528. def get_domain_data(module):
  529. try:
  530. domain_data = get_hooks('domains')
  531. if module in domain_data:
  532. return _dict(get_attr(get_hooks('domains')[module][0] + '.data'))
  533. else:
  534. return _dict()
  535. except ImportError:
  536. if local.flags.in_test:
  537. return _dict()
  538. else:
  539. raise
  540. def clear_cache(user=None, doctype=None):
  541. """Clear **User**, **DocType** or global cache.
  542. :param user: If user is given, only user cache is cleared.
  543. :param doctype: If doctype is given, only DocType cache is cleared."""
  544. import frappe.cache_manager
  545. if doctype:
  546. frappe.cache_manager.clear_doctype_cache(doctype)
  547. reset_metadata_version()
  548. elif user:
  549. frappe.cache_manager.clear_user_cache(user)
  550. else: # everything
  551. from frappe import translate
  552. frappe.cache_manager.clear_user_cache()
  553. frappe.cache_manager.clear_domain_cache()
  554. translate.clear_cache()
  555. reset_metadata_version()
  556. local.cache = {}
  557. local.new_doc_templates = {}
  558. for fn in get_hooks("clear_cache"):
  559. get_attr(fn)()
  560. local.role_permissions = {}
  561. def only_has_select_perm(doctype, user=None, ignore_permissions=False):
  562. if ignore_permissions:
  563. return False
  564. if not user:
  565. user = local.session.user
  566. import frappe.permissions
  567. permissions = frappe.permissions.get_role_permissions(doctype, user=user)
  568. if permissions.get('select') and not permissions.get('read'):
  569. return True
  570. else:
  571. return False
  572. def has_permission(doctype=None, ptype="read", doc=None, user=None, verbose=False, throw=False):
  573. """Raises `frappe.PermissionError` if not permitted.
  574. :param doctype: DocType for which permission is to be check.
  575. :param ptype: Permission type (`read`, `write`, `create`, `submit`, `cancel`, `amend`). Default: `read`.
  576. :param doc: [optional] Checks User permissions for given doc.
  577. :param user: [optional] Check for given user. Default: current user."""
  578. if not doctype and doc:
  579. doctype = doc.doctype
  580. import frappe.permissions
  581. out = frappe.permissions.has_permission(doctype, ptype, doc=doc, verbose=verbose, user=user, raise_exception=throw)
  582. if throw and not out:
  583. if doc:
  584. frappe.throw(_("No permission for {0}").format(doc.doctype + " " + doc.name))
  585. else:
  586. frappe.throw(_("No permission for {0}").format(doctype))
  587. return out
  588. def has_website_permission(doc=None, ptype='read', user=None, verbose=False, doctype=None):
  589. """Raises `frappe.PermissionError` if not permitted.
  590. :param doctype: DocType for which permission is to be check.
  591. :param ptype: Permission type (`read`, `write`, `create`, `submit`, `cancel`, `amend`). Default: `read`.
  592. :param doc: Checks User permissions for given doc.
  593. :param user: [optional] Check for given user. Default: current user."""
  594. if not user:
  595. user = session.user
  596. if doc:
  597. if isinstance(doc, str):
  598. doc = get_doc(doctype, doc)
  599. doctype = doc.doctype
  600. if doc.flags.ignore_permissions:
  601. return True
  602. # check permission in controller
  603. if hasattr(doc, 'has_website_permission'):
  604. return doc.has_website_permission(ptype, user, verbose=verbose)
  605. hooks = (get_hooks("has_website_permission") or {}).get(doctype, [])
  606. if hooks:
  607. for method in hooks:
  608. result = call(method, doc=doc, ptype=ptype, user=user, verbose=verbose)
  609. # if even a single permission check is Falsy
  610. if not result:
  611. return False
  612. # else it is Truthy
  613. return True
  614. else:
  615. return False
  616. def is_table(doctype):
  617. """Returns True if `istable` property (indicating child Table) is set for given DocType."""
  618. def get_tables():
  619. return db.sql_list("select name from tabDocType where istable=1")
  620. tables = cache().get_value("is_table", get_tables)
  621. return doctype in tables
  622. def get_precision(doctype, fieldname, currency=None, doc=None):
  623. """Get precision for a given field"""
  624. from frappe.model.meta import get_field_precision
  625. return get_field_precision(get_meta(doctype).get_field(fieldname), doc, currency)
  626. def generate_hash(txt=None, length=None):
  627. """Generates random hash for given text + current timestamp + random string."""
  628. import hashlib, time
  629. from .utils import random_string
  630. digest = hashlib.sha224(((txt or "") + repr(time.time()) + repr(random_string(8))).encode()).hexdigest()
  631. if length:
  632. digest = digest[:length]
  633. return digest
  634. def reset_metadata_version():
  635. """Reset `metadata_version` (Client (Javascript) build ID) hash."""
  636. v = generate_hash()
  637. cache().set_value("metadata_version", v)
  638. return v
  639. def new_doc(doctype, parent_doc=None, parentfield=None, as_dict=False):
  640. """Returns a new document of the given DocType with defaults set.
  641. :param doctype: DocType of the new document.
  642. :param parent_doc: [optional] add to parent document.
  643. :param parentfield: [optional] add against this `parentfield`."""
  644. from frappe.model.create_new import get_new_doc
  645. return get_new_doc(doctype, parent_doc, parentfield, as_dict=as_dict)
  646. def set_value(doctype, docname, fieldname, value=None):
  647. """Set document value. Calls `frappe.client.set_value`"""
  648. import frappe.client
  649. return frappe.client.set_value(doctype, docname, fieldname, value)
  650. def get_cached_doc(*args, **kwargs):
  651. if args and len(args) > 1 and isinstance(args[1], str):
  652. key = get_document_cache_key(args[0], args[1])
  653. # local cache
  654. doc = local.document_cache.get(key)
  655. if doc:
  656. return doc
  657. # redis cache
  658. doc = cache().hget('document_cache', key)
  659. if doc:
  660. doc = get_doc(doc)
  661. local.document_cache[key] = doc
  662. return doc
  663. # database
  664. doc = get_doc(*args, **kwargs)
  665. return doc
  666. def get_document_cache_key(doctype, name):
  667. return '{0}::{1}'.format(doctype, name)
  668. def clear_document_cache(doctype, name):
  669. cache().hdel("last_modified", doctype)
  670. key = get_document_cache_key(doctype, name)
  671. if key in local.document_cache:
  672. del local.document_cache[key]
  673. cache().hdel('document_cache', key)
  674. def get_cached_value(doctype, name, fieldname, as_dict=False):
  675. doc = get_cached_doc(doctype, name)
  676. if isinstance(fieldname, str):
  677. if as_dict:
  678. throw('Cannot make dict for single fieldname')
  679. return doc.get(fieldname)
  680. values = [doc.get(f) for f in fieldname]
  681. if as_dict:
  682. return _dict(zip(fieldname, values))
  683. return values
  684. def get_doc(*args, **kwargs):
  685. """Return a `frappe.model.document.Document` object of the given type and name.
  686. :param arg1: DocType name as string **or** document JSON.
  687. :param arg2: [optional] Document name as string.
  688. Examples:
  689. # insert a new document
  690. todo = frappe.get_doc({"doctype":"ToDo", "description": "test"})
  691. todo.insert()
  692. # open an existing document
  693. todo = frappe.get_doc("ToDo", "TD0001")
  694. """
  695. import frappe.model.document
  696. doc = frappe.model.document.get_doc(*args, **kwargs)
  697. # set in cache
  698. if args and len(args) > 1:
  699. key = get_document_cache_key(args[0], args[1])
  700. local.document_cache[key] = doc
  701. cache().hset('document_cache', key, doc.as_dict())
  702. return doc
  703. def get_last_doc(doctype, filters=None, order_by="creation desc"):
  704. """Get last created document of this type."""
  705. d = get_all(
  706. doctype,
  707. filters=filters,
  708. limit_page_length=1,
  709. order_by=order_by,
  710. pluck="name"
  711. )
  712. if d:
  713. return get_doc(doctype, d[0])
  714. else:
  715. raise DoesNotExistError
  716. def get_single(doctype):
  717. """Return a `frappe.model.document.Document` object of the given Single doctype."""
  718. return get_doc(doctype, doctype)
  719. def get_meta(doctype, cached=True):
  720. """Get `frappe.model.meta.Meta` instance of given doctype name."""
  721. import frappe.model.meta
  722. return frappe.model.meta.get_meta(doctype, cached=cached)
  723. def get_meta_module(doctype):
  724. import frappe.modules
  725. return frappe.modules.load_doctype_module(doctype)
  726. def delete_doc(doctype=None, name=None, force=0, ignore_doctypes=None, for_reload=False,
  727. ignore_permissions=False, flags=None, ignore_on_trash=False, ignore_missing=True, delete_permanently=False):
  728. """Delete a document. Calls `frappe.model.delete_doc.delete_doc`.
  729. :param doctype: DocType of document to be delete.
  730. :param name: Name of document to be delete.
  731. :param force: Allow even if document is linked. Warning: This may lead to data integrity errors.
  732. :param ignore_doctypes: Ignore if child table is one of these.
  733. :param for_reload: Call `before_reload` trigger before deleting.
  734. :param ignore_permissions: Ignore user permissions.
  735. :param delete_permanently: Do not create a Deleted Document for the document."""
  736. import frappe.model.delete_doc
  737. frappe.model.delete_doc.delete_doc(doctype, name, force, ignore_doctypes, for_reload,
  738. ignore_permissions, flags, ignore_on_trash, ignore_missing, delete_permanently)
  739. def delete_doc_if_exists(doctype, name, force=0):
  740. """Delete document if exists."""
  741. if db.exists(doctype, name):
  742. delete_doc(doctype, name, force=force)
  743. def reload_doctype(doctype, force=False, reset_permissions=False):
  744. """Reload DocType from model (`[module]/[doctype]/[name]/[name].json`) files."""
  745. reload_doc(scrub(db.get_value("DocType", doctype, "module")), "doctype", scrub(doctype),
  746. force=force, reset_permissions=reset_permissions)
  747. def reload_doc(module, dt=None, dn=None, force=False, reset_permissions=False):
  748. """Reload Document from model (`[module]/[doctype]/[name]/[name].json`) files.
  749. :param module: Module name.
  750. :param dt: DocType name.
  751. :param dn: Document name.
  752. :param force: Reload even if `modified` timestamp matches.
  753. """
  754. import frappe.modules
  755. return frappe.modules.reload_doc(module, dt, dn, force=force, reset_permissions=reset_permissions)
  756. @whitelist()
  757. def rename_doc(*args, **kwargs):
  758. """
  759. Renames a doc(dt, old) to doc(dt, new) and updates all linked fields of type "Link"
  760. Calls `frappe.model.rename_doc.rename_doc`
  761. """
  762. kwargs.pop('ignore_permissions', None)
  763. kwargs.pop('cmd', None)
  764. from frappe.model.rename_doc import rename_doc
  765. return rename_doc(*args, **kwargs)
  766. def get_module(modulename):
  767. """Returns a module object for given Python module name using `importlib.import_module`."""
  768. return importlib.import_module(modulename)
  769. def scrub(txt):
  770. """Returns sluggified string. e.g. `Sales Order` becomes `sales_order`."""
  771. return txt.replace(' ', '_').replace('-', '_').lower()
  772. def unscrub(txt):
  773. """Returns titlified string. e.g. `sales_order` becomes `Sales Order`."""
  774. return txt.replace('_', ' ').replace('-', ' ').title()
  775. def get_module_path(module, *joins):
  776. """Get the path of the given module name.
  777. :param module: Module name.
  778. :param *joins: Join additional path elements using `os.path.join`."""
  779. module = scrub(module)
  780. return get_pymodule_path(local.module_app[module] + "." + module, *joins)
  781. def get_app_path(app_name, *joins):
  782. """Return path of given app.
  783. :param app: App name.
  784. :param *joins: Join additional path elements using `os.path.join`."""
  785. return get_pymodule_path(app_name, *joins)
  786. def get_site_path(*joins):
  787. """Return path of current site.
  788. :param *joins: Join additional path elements using `os.path.join`."""
  789. return os.path.join(local.site_path, *joins)
  790. def get_pymodule_path(modulename, *joins):
  791. """Return path of given Python module name.
  792. :param modulename: Python module name.
  793. :param *joins: Join additional path elements using `os.path.join`."""
  794. if not "public" in joins:
  795. joins = [scrub(part) for part in joins]
  796. return os.path.join(os.path.dirname(get_module(scrub(modulename)).__file__ or ''), *joins)
  797. def get_module_list(app_name):
  798. """Get list of modules for given all via `app/modules.txt`."""
  799. return get_file_items(os.path.join(os.path.dirname(get_module(app_name).__file__), "modules.txt"))
  800. def get_all_apps(with_internal_apps=True, sites_path=None):
  801. """Get list of all apps via `sites/apps.txt`."""
  802. if not sites_path:
  803. sites_path = local.sites_path
  804. apps = get_file_items(os.path.join(sites_path, "apps.txt"), raise_not_found=True)
  805. if with_internal_apps:
  806. for app in get_file_items(os.path.join(local.site_path, "apps.txt")):
  807. if app not in apps:
  808. apps.append(app)
  809. if "frappe" in apps:
  810. apps.remove("frappe")
  811. apps.insert(0, 'frappe')
  812. return apps
  813. def get_installed_apps(sort=False, frappe_last=False):
  814. """Get list of installed apps in current site."""
  815. if getattr(flags, "in_install_db", True):
  816. return []
  817. if not db:
  818. connect()
  819. if not local.all_apps:
  820. local.all_apps = cache().get_value('all_apps', get_all_apps)
  821. installed = json.loads(db.get_global("installed_apps") or "[]")
  822. if sort:
  823. installed = [app for app in local.all_apps if app in installed]
  824. if frappe_last:
  825. if 'frappe' in installed:
  826. installed.remove('frappe')
  827. installed.append('frappe')
  828. return installed
  829. def get_doc_hooks():
  830. '''Returns hooked methods for given doc. It will expand the dict tuple if required.'''
  831. if not hasattr(local, 'doc_events_hooks'):
  832. hooks = get_hooks('doc_events', {})
  833. out = {}
  834. for key, value in hooks.items():
  835. if isinstance(key, tuple):
  836. for doctype in key:
  837. append_hook(out, doctype, value)
  838. else:
  839. append_hook(out, key, value)
  840. local.doc_events_hooks = out
  841. return local.doc_events_hooks
  842. def get_hooks(hook=None, default=None, app_name=None):
  843. """Get hooks via `app/hooks.py`
  844. :param hook: Name of the hook. Will gather all hooks for this name and return as a list.
  845. :param default: Default if no hook found.
  846. :param app_name: Filter by app."""
  847. def load_app_hooks(app_name=None):
  848. hooks = {}
  849. for app in [app_name] if app_name else get_installed_apps(sort=True):
  850. app = "frappe" if app=="webnotes" else app
  851. try:
  852. app_hooks = get_module(app + ".hooks")
  853. except ImportError:
  854. if local.flags.in_install_app:
  855. # if app is not installed while restoring
  856. # ignore it
  857. pass
  858. print('Could not find app "{0}"'.format(app_name))
  859. if not request:
  860. sys.exit(1)
  861. raise
  862. for key in dir(app_hooks):
  863. if not key.startswith("_"):
  864. append_hook(hooks, key, getattr(app_hooks, key))
  865. return hooks
  866. no_cache = conf.developer_mode or False
  867. if app_name:
  868. hooks = _dict(load_app_hooks(app_name))
  869. else:
  870. if no_cache:
  871. hooks = _dict(load_app_hooks())
  872. else:
  873. hooks = _dict(cache().get_value("app_hooks", load_app_hooks))
  874. if hook:
  875. return hooks.get(hook) or (default if default is not None else [])
  876. else:
  877. return hooks
  878. def append_hook(target, key, value):
  879. '''appends a hook to the the target dict.
  880. If the hook key, exists, it will make it a key.
  881. If the hook value is a dict, like doc_events, it will
  882. listify the values against the key.
  883. '''
  884. if isinstance(value, dict):
  885. # dict? make a list of values against each key
  886. target.setdefault(key, {})
  887. for inkey in value:
  888. append_hook(target[key], inkey, value[inkey])
  889. else:
  890. # make a list
  891. target.setdefault(key, [])
  892. if not isinstance(value, list):
  893. value = [value]
  894. target[key].extend(value)
  895. def setup_module_map():
  896. """Rebuild map of all modules (internal)."""
  897. _cache = cache()
  898. if conf.db_name:
  899. local.app_modules = _cache.get_value("app_modules")
  900. local.module_app = _cache.get_value("module_app")
  901. if not (local.app_modules and local.module_app):
  902. local.module_app, local.app_modules = {}, {}
  903. for app in get_all_apps(with_internal_apps=True):
  904. local.app_modules.setdefault(app, [])
  905. for module in get_module_list(app):
  906. module = scrub(module)
  907. local.module_app[module] = app
  908. local.app_modules[app].append(module)
  909. if conf.db_name:
  910. _cache.set_value("app_modules", local.app_modules)
  911. _cache.set_value("module_app", local.module_app)
  912. def get_file_items(path, raise_not_found=False, ignore_empty_lines=True):
  913. """Returns items from text file as a list. Ignores empty lines."""
  914. import frappe.utils
  915. content = read_file(path, raise_not_found=raise_not_found)
  916. if content:
  917. content = frappe.utils.strip(content)
  918. return [
  919. p.strip() for p in content.splitlines()
  920. if (not ignore_empty_lines) or (p.strip() and not p.startswith("#"))
  921. ]
  922. else:
  923. return []
  924. def get_file_json(path):
  925. """Read a file and return parsed JSON object."""
  926. with open(path, 'r') as f:
  927. return json.load(f)
  928. def read_file(path, raise_not_found=False):
  929. """Open a file and return its content as Unicode."""
  930. if isinstance(path, str):
  931. path = path.encode("utf-8")
  932. if os.path.exists(path):
  933. with open(path, "r") as f:
  934. return as_unicode(f.read())
  935. elif raise_not_found:
  936. raise IOError("{} Not Found".format(path))
  937. else:
  938. return None
  939. def get_attr(method_string):
  940. """Get python method object from its name."""
  941. app_name = method_string.split(".")[0]
  942. if not local.flags.in_install and app_name not in get_installed_apps():
  943. throw(_("App {0} is not installed").format(app_name), AppNotInstalledError)
  944. modulename = '.'.join(method_string.split('.')[:-1])
  945. methodname = method_string.split('.')[-1]
  946. return getattr(get_module(modulename), methodname)
  947. def call(fn, *args, **kwargs):
  948. """Call a function and match arguments."""
  949. if isinstance(fn, str):
  950. fn = get_attr(fn)
  951. newargs = get_newargs(fn, kwargs)
  952. return fn(*args, **newargs)
  953. def get_newargs(fn, kwargs):
  954. if hasattr(fn, 'fnargs'):
  955. fnargs = fn.fnargs
  956. else:
  957. fnargs = inspect.getfullargspec(fn).args
  958. fnargs.extend(inspect.getfullargspec(fn).kwonlyargs)
  959. varkw = inspect.getfullargspec(fn).varkw
  960. newargs = {}
  961. for a in kwargs:
  962. if (a in fnargs) or varkw:
  963. newargs[a] = kwargs.get(a)
  964. newargs.pop("ignore_permissions", None)
  965. newargs.pop("flags", None)
  966. return newargs
  967. def make_property_setter(args, ignore_validate=False, validate_fields_for_doctype=True):
  968. """Create a new **Property Setter** (for overriding DocType and DocField properties).
  969. If doctype is not specified, it will create a property setter for all fields with the
  970. given fieldname"""
  971. args = _dict(args)
  972. if not args.doctype_or_field:
  973. args.doctype_or_field = 'DocField'
  974. if not args.property_type:
  975. args.property_type = db.get_value('DocField',
  976. {'parent': 'DocField', 'fieldname': args.property}, 'fieldtype') or 'Data'
  977. if not args.doctype:
  978. doctype_list = db.sql_list('select distinct parent from tabDocField where fieldname=%s', args.fieldname)
  979. else:
  980. doctype_list = [args.doctype]
  981. for doctype in doctype_list:
  982. if not args.property_type:
  983. args.property_type = db.get_value('DocField',
  984. {'parent': doctype, 'fieldname': args.fieldname}, 'fieldtype') or 'Data'
  985. ps = get_doc({
  986. 'doctype': "Property Setter",
  987. 'doctype_or_field': args.doctype_or_field,
  988. 'doc_type': doctype,
  989. 'field_name': args.fieldname,
  990. 'row_name': args.row_name,
  991. 'property': args.property,
  992. 'value': args.value,
  993. 'property_type': args.property_type or "Data",
  994. '__islocal': 1
  995. })
  996. ps.flags.ignore_validate = ignore_validate
  997. ps.flags.validate_fields_for_doctype = validate_fields_for_doctype
  998. ps.validate_fieldtype_change()
  999. ps.insert()
  1000. def import_doc(path):
  1001. """Import a file using Data Import."""
  1002. from frappe.core.doctype.data_import.data_import import import_doc
  1003. import_doc(path)
  1004. def copy_doc(doc, ignore_no_copy=True):
  1005. """ No_copy fields also get copied."""
  1006. import copy
  1007. def remove_no_copy_fields(d):
  1008. for df in d.meta.get("fields", {"no_copy": 1}):
  1009. if hasattr(d, df.fieldname):
  1010. d.set(df.fieldname, None)
  1011. fields_to_clear = ['name', 'owner', 'creation', 'modified', 'modified_by']
  1012. if not local.flags.in_test:
  1013. fields_to_clear.append("docstatus")
  1014. if not isinstance(doc, dict):
  1015. d = doc.as_dict()
  1016. else:
  1017. d = doc
  1018. newdoc = get_doc(copy.deepcopy(d))
  1019. newdoc.set("__islocal", 1)
  1020. for fieldname in (fields_to_clear + ['amended_from', 'amendment_date']):
  1021. newdoc.set(fieldname, None)
  1022. if not ignore_no_copy:
  1023. remove_no_copy_fields(newdoc)
  1024. for i, d in enumerate(newdoc.get_all_children()):
  1025. d.set("__islocal", 1)
  1026. for fieldname in fields_to_clear:
  1027. d.set(fieldname, None)
  1028. if not ignore_no_copy:
  1029. remove_no_copy_fields(d)
  1030. return newdoc
  1031. def compare(val1, condition, val2):
  1032. """Compare two values using `frappe.utils.compare`
  1033. `condition` could be:
  1034. - "^"
  1035. - "in"
  1036. - "not in"
  1037. - "="
  1038. - "!="
  1039. - ">"
  1040. - "<"
  1041. - ">="
  1042. - "<="
  1043. - "not None"
  1044. - "None"
  1045. """
  1046. import frappe.utils
  1047. return frappe.utils.compare(val1, condition, val2)
  1048. def respond_as_web_page(title, html, success=None, http_status_code=None, context=None,
  1049. indicator_color=None, primary_action='/', primary_label = None, fullpage=False,
  1050. width=None, template='message'):
  1051. """Send response as a web page with a message rather than JSON. Used to show permission errors etc.
  1052. :param title: Page title and heading.
  1053. :param message: Message to be shown.
  1054. :param success: Alert message.
  1055. :param http_status_code: HTTP status code
  1056. :param context: web template context
  1057. :param indicator_color: color of indicator in title
  1058. :param primary_action: route on primary button (default is `/`)
  1059. :param primary_label: label on primary button (default is "Home")
  1060. :param fullpage: hide header / footer
  1061. :param width: Width of message in pixels
  1062. :param template: Optionally pass view template
  1063. """
  1064. local.message_title = title
  1065. local.message = html
  1066. local.response['type'] = 'page'
  1067. local.response['route'] = template
  1068. local.no_cache = 1
  1069. if http_status_code:
  1070. local.response['http_status_code'] = http_status_code
  1071. if not context:
  1072. context = {}
  1073. if not indicator_color:
  1074. if success:
  1075. indicator_color = 'green'
  1076. elif http_status_code and http_status_code > 300:
  1077. indicator_color = 'red'
  1078. else:
  1079. indicator_color = 'blue'
  1080. context['indicator_color'] = indicator_color
  1081. context['primary_label'] = primary_label
  1082. context['primary_action'] = primary_action
  1083. context['error_code'] = http_status_code
  1084. context['fullpage'] = fullpage
  1085. if width:
  1086. context['card_width'] = width
  1087. local.response['context'] = context
  1088. def redirect_to_message(title, html, http_status_code=None, context=None, indicator_color=None):
  1089. """Redirects to /message?id=random
  1090. Similar to respond_as_web_page, but used to 'redirect' and show message pages like success, failure, etc. with a detailed message
  1091. :param title: Page title and heading.
  1092. :param message: Message to be shown.
  1093. :param http_status_code: HTTP status code.
  1094. Example Usage:
  1095. frappe.redirect_to_message(_('Thank you'), "<div><p>You will receive an email at test@example.com</p></div>")
  1096. """
  1097. message_id = generate_hash(length=8)
  1098. message = {
  1099. 'context': context or {},
  1100. 'http_status_code': http_status_code or 200
  1101. }
  1102. message['context'].update({
  1103. 'header': title,
  1104. 'title': title,
  1105. 'message': html
  1106. })
  1107. if indicator_color:
  1108. message['context'].update({
  1109. "indicator_color": indicator_color
  1110. })
  1111. cache().set_value("message_id:{0}".format(message_id), message, expires_in_sec=60)
  1112. location = '/message?id={0}'.format(message_id)
  1113. if not getattr(local, 'is_ajax', False):
  1114. local.response["type"] = "redirect"
  1115. local.response["location"] = location
  1116. else:
  1117. return location
  1118. def build_match_conditions(doctype, as_condition=True):
  1119. """Return match (User permissions) for given doctype as list or SQL."""
  1120. import frappe.desk.reportview
  1121. return frappe.desk.reportview.build_match_conditions(doctype, as_condition=as_condition)
  1122. def get_list(doctype, *args, **kwargs):
  1123. """List database query via `frappe.model.db_query`. Will also check for permissions.
  1124. :param doctype: DocType on which query is to be made.
  1125. :param fields: List of fields or `*`.
  1126. :param filters: List of filters (see example).
  1127. :param order_by: Order By e.g. `modified desc`.
  1128. :param limit_page_start: Start results at record #. Default 0.
  1129. :param limit_page_length: No of records in the page. Default 20.
  1130. Example usage:
  1131. # simple dict filter
  1132. frappe.get_list("ToDo", fields=["name", "description"], filters = {"owner":"test@example.com"})
  1133. # filter as a list of lists
  1134. frappe.get_list("ToDo", fields="*", filters = [["modified", ">", "2014-01-01"]])
  1135. # filter as a list of dicts
  1136. frappe.get_list("ToDo", fields="*", filters = {"description": ("like", "test%")})
  1137. """
  1138. import frappe.model.db_query
  1139. return frappe.model.db_query.DatabaseQuery(doctype).execute(*args, **kwargs)
  1140. def get_all(doctype, *args, **kwargs):
  1141. """List database query via `frappe.model.db_query`. Will **not** check for permissions.
  1142. Parameters are same as `frappe.get_list`
  1143. :param doctype: DocType on which query is to be made.
  1144. :param fields: List of fields or `*`. Default is: `["name"]`.
  1145. :param filters: List of filters (see example).
  1146. :param order_by: Order By e.g. `modified desc`.
  1147. :param limit_start: Start results at record #. Default 0.
  1148. :param limit_page_length: No of records in the page. Default 20.
  1149. Example usage:
  1150. # simple dict filter
  1151. frappe.get_all("ToDo", fields=["name", "description"], filters = {"owner":"test@example.com"})
  1152. # filter as a list of lists
  1153. frappe.get_all("ToDo", fields=["*"], filters = [["modified", ">", "2014-01-01"]])
  1154. # filter as a list of dicts
  1155. frappe.get_all("ToDo", fields=["*"], filters = {"description": ("like", "test%")})
  1156. """
  1157. kwargs["ignore_permissions"] = True
  1158. if not "limit_page_length" in kwargs:
  1159. kwargs["limit_page_length"] = 0
  1160. return get_list(doctype, *args, **kwargs)
  1161. def get_value(*args, **kwargs):
  1162. """Returns a document property or list of properties.
  1163. Alias for `frappe.db.get_value`
  1164. :param doctype: DocType name.
  1165. :param filters: Filters like `{"x":"y"}` or name of the document. `None` if Single DocType.
  1166. :param fieldname: Column name.
  1167. :param ignore: Don't raise exception if table, column is missing.
  1168. :param as_dict: Return values as dict.
  1169. :param debug: Print query in error log.
  1170. """
  1171. return db.get_value(*args, **kwargs)
  1172. def as_json(obj, indent=1):
  1173. from frappe.utils.response import json_handler
  1174. try:
  1175. return json.dumps(obj, indent=indent, sort_keys=True, default=json_handler, separators=(',', ': '))
  1176. except TypeError:
  1177. return json.dumps(obj, indent=indent, default=json_handler, separators=(',', ': '))
  1178. def are_emails_muted():
  1179. from frappe.utils import cint
  1180. return flags.mute_emails or cint(conf.get("mute_emails") or 0) or False
  1181. def get_test_records(doctype):
  1182. """Returns list of objects from `test_records.json` in the given doctype's folder."""
  1183. from frappe.modules import get_doctype_module, get_module_path
  1184. path = os.path.join(get_module_path(get_doctype_module(doctype)), "doctype", scrub(doctype), "test_records.json")
  1185. if os.path.exists(path):
  1186. with open(path, "r") as f:
  1187. return json.loads(f.read())
  1188. else:
  1189. return []
  1190. def format_value(*args, **kwargs):
  1191. """Format value with given field properties.
  1192. :param value: Value to be formatted.
  1193. :param df: (Optional) DocField object with properties `fieldtype`, `options` etc."""
  1194. import frappe.utils.formatters
  1195. return frappe.utils.formatters.format_value(*args, **kwargs)
  1196. def format(*args, **kwargs):
  1197. """Format value with given field properties.
  1198. :param value: Value to be formatted.
  1199. :param df: (Optional) DocField object with properties `fieldtype`, `options` etc."""
  1200. import frappe.utils.formatters
  1201. return frappe.utils.formatters.format_value(*args, **kwargs)
  1202. def get_print(doctype=None, name=None, print_format=None, style=None,
  1203. html=None, as_pdf=False, doc=None, output=None, no_letterhead=0, password=None):
  1204. """Get Print Format for given document.
  1205. :param doctype: DocType of document.
  1206. :param name: Name of document.
  1207. :param print_format: Print Format name. Default 'Standard',
  1208. :param style: Print Format style.
  1209. :param as_pdf: Return as PDF. Default False.
  1210. :param password: Password to encrypt the pdf with. Default None"""
  1211. from frappe.website.serve import get_response_content
  1212. from frappe.utils.pdf import get_pdf
  1213. local.form_dict.doctype = doctype
  1214. local.form_dict.name = name
  1215. local.form_dict.format = print_format
  1216. local.form_dict.style = style
  1217. local.form_dict.doc = doc
  1218. local.form_dict.no_letterhead = no_letterhead
  1219. options = None
  1220. if password:
  1221. options = {'password': password}
  1222. if not html:
  1223. html = get_response_content("printview")
  1224. if as_pdf:
  1225. return get_pdf(html, output = output, options = options)
  1226. else:
  1227. return html
  1228. def attach_print(doctype, name, file_name=None, print_format=None,
  1229. style=None, html=None, doc=None, lang=None, print_letterhead=True, password=None):
  1230. from frappe.utils import scrub_urls
  1231. if not file_name: file_name = name
  1232. file_name = file_name.replace(' ','').replace('/','-')
  1233. print_settings = db.get_singles_dict("Print Settings")
  1234. _lang = local.lang
  1235. #set lang as specified in print format attachment
  1236. if lang: local.lang = lang
  1237. local.flags.ignore_print_permissions = True
  1238. no_letterhead = not print_letterhead
  1239. kwargs = dict(
  1240. print_format=print_format,
  1241. style=style,
  1242. html=html,
  1243. doc=doc,
  1244. no_letterhead=no_letterhead,
  1245. password=password
  1246. )
  1247. content = ''
  1248. if int(print_settings.send_print_as_pdf or 0):
  1249. ext = ".pdf"
  1250. kwargs["as_pdf"] = True
  1251. content = get_print(doctype, name, **kwargs)
  1252. else:
  1253. ext = ".html"
  1254. content = scrub_urls(get_print(doctype, name, **kwargs)).encode('utf-8')
  1255. out = {
  1256. "fname": file_name + ext,
  1257. "fcontent": content
  1258. }
  1259. local.flags.ignore_print_permissions = False
  1260. #reset lang to original local lang
  1261. local.lang = _lang
  1262. return out
  1263. def publish_progress(*args, **kwargs):
  1264. """Show the user progress for a long request
  1265. :param percent: Percent progress
  1266. :param title: Title
  1267. :param doctype: Optional, for document type
  1268. :param docname: Optional, for document name
  1269. :param description: Optional description
  1270. """
  1271. import frappe.realtime
  1272. return frappe.realtime.publish_progress(*args, **kwargs)
  1273. def publish_realtime(*args, **kwargs):
  1274. """Publish real-time updates
  1275. :param event: Event name, like `task_progress` etc.
  1276. :param message: JSON message object. For async must contain `task_id`
  1277. :param room: Room in which to publish update (default entire site)
  1278. :param user: Transmit to user
  1279. :param doctype: Transmit to doctype, docname
  1280. :param docname: Transmit to doctype, docname
  1281. :param after_commit: (default False) will emit after current transaction is committed
  1282. """
  1283. import frappe.realtime
  1284. return frappe.realtime.publish_realtime(*args, **kwargs)
  1285. def local_cache(namespace, key, generator, regenerate_if_none=False):
  1286. """A key value store for caching within a request
  1287. :param namespace: frappe.local.cache[namespace]
  1288. :param key: frappe.local.cache[namespace][key] used to retrieve value
  1289. :param generator: method to generate a value if not found in store
  1290. """
  1291. if namespace not in local.cache:
  1292. local.cache[namespace] = {}
  1293. if key not in local.cache[namespace]:
  1294. local.cache[namespace][key] = generator()
  1295. elif local.cache[namespace][key]==None and regenerate_if_none:
  1296. # if key exists but the previous result was None
  1297. local.cache[namespace][key] = generator()
  1298. return local.cache[namespace][key]
  1299. def enqueue(*args, **kwargs):
  1300. '''
  1301. Enqueue method to be executed using a background worker
  1302. :param method: method string or method object
  1303. :param queue: (optional) should be either long, default or short
  1304. :param timeout: (optional) should be set according to the functions
  1305. :param event: this is passed to enable clearing of jobs from queues
  1306. :param is_async: (optional) if is_async=False, the method is executed immediately, else via a worker
  1307. :param job_name: (optional) can be used to name an enqueue call, which can be used to prevent duplicate calls
  1308. :param kwargs: keyword arguments to be passed to the method
  1309. '''
  1310. import frappe.utils.background_jobs
  1311. return frappe.utils.background_jobs.enqueue(*args, **kwargs)
  1312. def task(**task_kwargs):
  1313. def decorator_task(f):
  1314. f.enqueue = lambda **fun_kwargs: enqueue(f, **task_kwargs, **fun_kwargs)
  1315. return f
  1316. return decorator_task
  1317. def enqueue_doc(*args, **kwargs):
  1318. '''
  1319. Enqueue method to be executed using a background worker
  1320. :param doctype: DocType of the document on which you want to run the event
  1321. :param name: Name of the document on which you want to run the event
  1322. :param method: method string or method object
  1323. :param queue: (optional) should be either long, default or short
  1324. :param timeout: (optional) should be set according to the functions
  1325. :param kwargs: keyword arguments to be passed to the method
  1326. '''
  1327. import frappe.utils.background_jobs
  1328. return frappe.utils.background_jobs.enqueue_doc(*args, **kwargs)
  1329. def get_doctype_app(doctype):
  1330. def _get_doctype_app():
  1331. doctype_module = local.db.get_value("DocType", doctype, "module")
  1332. return local.module_app[scrub(doctype_module)]
  1333. return local_cache("doctype_app", doctype, generator=_get_doctype_app)
  1334. loggers = {}
  1335. log_level = None
  1336. def logger(module=None, with_more_info=False, allow_site=True, filter=None, max_size=100_000, file_count=20):
  1337. '''Returns a python logger that uses StreamHandler'''
  1338. from frappe.utils.logger import get_logger
  1339. return get_logger(module=module, with_more_info=with_more_info, allow_site=allow_site, filter=filter, max_size=max_size, file_count=file_count)
  1340. def log_error(message=None, title=_("Error")):
  1341. '''Log error to Error Log'''
  1342. # AI ALERT:
  1343. # the title and message may be swapped
  1344. # the better API for this is log_error(title, message), and used in many cases this way
  1345. # this hack tries to be smart about whats a title (single line ;-)) and fixes it
  1346. if message:
  1347. if '\n' in title:
  1348. error, title = title, message
  1349. else:
  1350. error = message
  1351. else:
  1352. error = get_traceback()
  1353. return get_doc(dict(doctype='Error Log', error=as_unicode(error),
  1354. method=title)).insert(ignore_permissions=True)
  1355. def get_desk_link(doctype, name):
  1356. html = '<a href="/app/Form/{doctype}/{name}" style="font-weight: bold;">{doctype_local} {name}</a>'
  1357. return html.format(
  1358. doctype=doctype,
  1359. name=name,
  1360. doctype_local=_(doctype)
  1361. )
  1362. def bold(text):
  1363. return '<strong>{0}</strong>'.format(text)
  1364. def safe_eval(code, eval_globals=None, eval_locals=None):
  1365. '''A safer `eval`'''
  1366. whitelisted_globals = {
  1367. "int": int,
  1368. "float": float,
  1369. "long": int,
  1370. "round": round
  1371. }
  1372. UNSAFE_ATTRIBUTES = {
  1373. # Generator Attributes
  1374. "gi_frame", "gi_code",
  1375. # Coroutine Attributes
  1376. "cr_frame", "cr_code", "cr_origin",
  1377. # Async Generator Attributes
  1378. "ag_code", "ag_frame",
  1379. # Traceback Attributes
  1380. "tb_frame", "tb_next",
  1381. # Format Attributes
  1382. "format", "format_map",
  1383. }
  1384. for attribute in UNSAFE_ATTRIBUTES:
  1385. if attribute in code:
  1386. throw('Illegal rule {0}. Cannot use "{1}"'.format(bold(code), attribute))
  1387. if '__' in code:
  1388. throw('Illegal rule {0}. Cannot use "__"'.format(bold(code)))
  1389. if not eval_globals:
  1390. eval_globals = {}
  1391. eval_globals['__builtins__'] = {}
  1392. eval_globals.update(whitelisted_globals)
  1393. return eval(code, eval_globals, eval_locals)
  1394. def get_system_settings(key):
  1395. if key not in local.system_settings:
  1396. local.system_settings.update({key: db.get_single_value('System Settings', key)})
  1397. return local.system_settings.get(key)
  1398. def get_active_domains():
  1399. from frappe.core.doctype.domain_settings.domain_settings import get_active_domains
  1400. return get_active_domains()
  1401. def get_version(doctype, name, limit=None, head=False, raise_err=True):
  1402. '''
  1403. Returns a list of version information of a given DocType.
  1404. Note: Applicable only if DocType has changes tracked.
  1405. Example
  1406. >>> frappe.get_version('User', 'foobar@gmail.com')
  1407. >>>
  1408. [
  1409. {
  1410. "version": [version.data], # Refer Version DocType get_diff method and data attribute
  1411. "user": "admin@gmail.com", # User that created this version
  1412. "creation": <datetime.datetime> # Creation timestamp of that object.
  1413. }
  1414. ]
  1415. '''
  1416. meta = get_meta(doctype)
  1417. if meta.track_changes:
  1418. names = db.get_all('Version', filters={
  1419. 'ref_doctype': doctype,
  1420. 'docname': name,
  1421. 'order_by': 'creation' if head else None,
  1422. 'limit': limit
  1423. }, as_list=1)
  1424. from frappe.chat.util import squashify, dictify, safe_json_loads
  1425. versions = []
  1426. for name in names:
  1427. name = squashify(name)
  1428. doc = get_doc('Version', name)
  1429. data = doc.data
  1430. data = safe_json_loads(data)
  1431. data = dictify(dict(
  1432. version=data,
  1433. user=doc.owner,
  1434. creation=doc.creation
  1435. ))
  1436. versions.append(data)
  1437. return versions
  1438. else:
  1439. if raise_err:
  1440. raise ValueError(_('{0} has no versions tracked.').format(doctype))
  1441. @whitelist(allow_guest=True)
  1442. def ping():
  1443. return "pong"
  1444. def safe_encode(param, encoding='utf-8'):
  1445. try:
  1446. param = param.encode(encoding)
  1447. except Exception:
  1448. pass
  1449. return param
  1450. def safe_decode(param, encoding='utf-8'):
  1451. try:
  1452. param = param.decode(encoding)
  1453. except Exception:
  1454. pass
  1455. return param
  1456. def parse_json(val):
  1457. from frappe.utils import parse_json
  1458. return parse_json(val)
  1459. def mock(type, size=1, locale='en'):
  1460. results = []
  1461. fake = faker.Faker(locale)
  1462. if type not in dir(fake):
  1463. raise ValueError('Not a valid mock type.')
  1464. else:
  1465. for i in range(size):
  1466. data = getattr(fake, type)()
  1467. results.append(data)
  1468. from frappe.chat.util import squashify
  1469. return squashify(results)
  1470. def validate_and_sanitize_search_inputs(fn):
  1471. from frappe.desk.search import validate_and_sanitize_search_inputs as func
  1472. return func(fn)