Utility Functions

TechMaju hadir dengan berbagai fungsi utilitas untuk menangani operasi umum dalam mengelola manajemen DateTime yang spesifik untuk situs, format tanggal dan mata uang, pembuatan PDF, dan banyak lagi.

Metode utilitas ini dapat diimpor dari modul frappe.utils (dan modul nested seperti frappe.utils.logger dan frappe.utils.data) dalam file Python mana pun dari aplikasi Anda.

now

now()

Mengembalikan datetime saat ini dalam format yyyy-mm-dd hh:mm:ss

frappe.utils.now() # '2021-05-25 06:38:52.242515'

getdate

getdate(string_date=None)

Mengonversi string_date (yyyy-mm-dd) menjadi objek datetime.date. Jika tidak ada input yang diberikan, tanggal saat ini dikembalikan. Melemparkan pengecualian jika string_date adalah string tanggal yang tidak valid.

frappe.utils.getdate() # datetime.date(2021, 5, 25)
frappe.utils.getdate('2000-03-18') # datetime.date(2000, 3, 18)

today

today()

Mengembalikan tanggal saat ini dalam format yyyy-mm-dd.

frappe.utils.today() # '2021-05-25'

add_to_date

add_to_date(date, years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, as_string=False, as_datetime=False)

`date`: Representasi string atau objek `datetime`, menggunakan `datetime` saat ini jika `None` yang diberikan
`as_string`: Kembalikan sebagai string
`as_datetime`: Jika `as_string` adalah True dan `as_datetime` juga True, mengembalikan `datetime` string jika tidak hanya `date` string.

Fungsi ini bisa sangat berguna untuk melakukan perbedaan tanggal/datetime, misalnya, menambahkan atau mengurangi jumlah hari tertentu dari tanggal/datetime tertentu.

today = frappe.utils.now() #'2024-07-07 17:33:41.356280'

after_10_days = frappe.utils.add_to_date(today, days=10, as_string=True)
print(after_10_days) # '2024-07-17'

add_to_date(today, months=2) # '2024-09-07'
add_to_date(today, days=10, as_string=True, as_datetime=True) # '2024-07-17 17:33:41.356280'
add_to_date(today, years=2) # '2026-07-07 17:33:41.356280'

date_diff

date_diff(date_2, date_1)

Mengembalikan perbedaan antara dua tanggal yang diberikan dalam hari.

date_1 = frappe.utils.today()
date_2 = frappe.utils.add_to_date(date_1, days=10)

log(frappe.utils.date_diff(date_2, date_1)) #10

days_diff

days_diff(date_2, date_1)

Mengembalikan perbedaan antara dua tanggal yang diberikan dalam hari.

date_1 = frappe.utils.today()
date_2 = frappe.utils.add_to_date(date_1, days=10)

log(frappe.utils.days_diff(date_2, date_1)) #10

month_diff

month_diff(date_2, date_1)

Mengembalikan perbedaan antara dua tanggal yang diberikan dalam bulan.

date_1 = "2024-07-01"
date_2 = frappe.utils.add_to_date(date_1, days=60)

log(frappe.utils.month_diff(date_2, date_1)) #2

pretty_date

pretty_date(iso_datetime)

Mengambil waktu ISO dan mengembalikan string yang mewakili berapa lama waktu telah berlalu. Sangat umum dalam aplikasi komunikasi seperti pesan instan.

frappe.utils.pretty_date(frappe.utils.now()) # 'baru saja'
# Beberapa contoh output:

# 1 jam yang lalu
# 20 menit yang lalu
# 1 minggu yang lalu
# 5 tahun yang lalu

format_duration

format_duration(seconds, hide_days=False)

Mengonversi nilai durasi yang diberikan dalam detik (float) ke format durasi.

frappe.utils.format_duration(50) # '50s'
frappe.utils.format_duration(10000) # '2h 46m 40s'
frappe.utils.format_duration(1000000) # '11d 13h 46m 40s'

# Mengonversi hari menjadi jam
frappe.utils.format_duration(1000000, hide_days=True) # '277h 46m 40s'

comma_and

comma_and(some_list, add_quotes=True)

Diberikan daftar atau tuple some_list, mengembalikan string dalam format 1st item, 2nd item, .... dan last item. Fungsi ini menggunakan frappe._, jadi Anda tidak perlu khawatir tentang terjemahan untuk kata dan. Jika add_quotes adalah False, mengembalikan item tanpa tanda kutip, dengan tanda kutip jika sebaliknya. Jika tipe some_list yang diteruskan sebagai argumen adalah sesuatu selain daftar atau tuple, some_list dikembalikan apa adanya.

frappe.utils.comma_and([1, 2, 3]) # "'1', '2' dan '3'"
frappe.utils.comma_and(['Apple', 'Ball', 'Cat'], add_quotes=False) # 'Apple, Ball dan Cat'
frappe.utils.comma_and('abcd') # 'abcd'

> Ada juga fungsi comma_or yang mirip dengan comma_and kecuali pemisahnya, yaitu or dalam kasus comma_or.

money_in_words

money_in_words(number, main_currency=None, fraction_currency=None)

`number`: Jumlah uang dengan floating point
`main_currency`: Menggunakan ini sebagai mata uang utama. Jika tidak diberikan, mencoba mengambil dari pengaturan default atau menggunakan `INR` jika tidak ditemukan di sana.

Fungsi ini mengembalikan string dalam bentuk kata-kata dengan mata uang utama dan mata uang pecahan.

frappe.utils.money_in_words(900) # 'INR Sembilan Ratus dan Lima Puluh Paisa only.'
frappe.utils.money_in_words(900.50) # 'INR Sembilan Ratus dan Lima Puluh Paisa only.'
frappe.utils.money_in_words(900.50, 'USD') # 'USD Sembilan Ratus dan Lima Puluh Centavo only.'
frappe.utils.money_in_words(900.50, 'USD', 'Cents') # 'USD Sembilan Ratus dan Lima Puluh Cents only.'

validate_json_string

validate_json_string(string)

Melemparkan frappe.ValidationError jika string yang diberikan adalah string JSON (JavaScript Object Notation) yang valid. Anda dapat menggunakan blok try-except untuk menangani panggilan ke fungsi ini seperti yang ditunjukkan dalam cuplikan kode di bawah ini.

# Tidak ada Pengecualian yang dilemparkan
frappe.utils.validate_json_string('[]')
frappe.utils.validate_json_string('[{}]')
frappe.utils.validate_json_string('[{"player": "one", "score": 199}]')

try:
    # Melemparkan frappe.ValidationError
    frappe.utils.validate_json_string('invalid json')
except frappe.ValidationError:
    log('Bukan string JSON yang valid')

random_string

random_string(length)

Fungsi ini menghasilkan string acak yang mengandung jumlah karakter length. Ini bisa berguna untuk kriptografi atau pembuatan rahasia untuk beberapa kasus.

frappe.utils.random_string(40) # 'mcrLCrlvkUdkaOe8m5xMI8IwDB8lszwJsWtZFveQ'
frappe.utils.random_string(<span="hljs-number">6) # 'htrB4L'
frappe.utils.random_string(<span="hljs-number">6) #'HNRirG'

unique

unique(seq)

seq: Sebuah iterable / Sequence

Fungsi ini mengembalikan daftar elemen dari sequence yang diberikan setelah menghapus duplikat. Juga, mempertahankan urutan, tidak seperti: list(set(seq)).

frappe.utils.unique([1, 2, 3, 1, 1, <span="hljs-number">1]) # [1, 2, 3]
frappe.utils.unique('abcda') # ['a', 'b', 'c', 'd']
frappe.utils.unique(('Apple', 'Apple', 'Banana', 'Apple')) # ['Apple', 'Banana']

get_pdf

get_pdf(html, options=None, output=None)

`html`: HTML string untuk dirender
`options`: Sebuah `dict` opsional untuk konfigurasi
`output`: Objek `PdfFileWriter` opsional.

Fungsi ini menggunakan modul pdfkit dan pyPDF2 untuk menghasilkan file PDF dari HTML. Jika output diberikan, halaman yang dihasilkan ditambahkan ke objek ini dan dikembalikan, jika tidak, mengembalikan aliran byte dari PDF.

Misalnya, menghasilkan dan mengembalikan PDF sebagai respons terhadap permintaan web:

    cart = [{
        'Samsung Galaxy S20': 10,
        'iPhone 13': 80
    }]

    html = '<h1>Invoice dari Star Electronics e-Store!</h1>'

    # Menambahkan item ke PDF HTML
    html += '<ol>'
    for item, qty in cart.items():
        html += f'<li>{item} - {qty}</li>'
    html += '</ol>'

    # Melampirkan PDF ke respons
    frappe.local.response.filename = 'invoice.pdf'
    frappe.local.response.filecontent = frappe.utils.pdf.get_pdf(html)
    frappe.local.response.type = 'pdf'

get_abbr

get_abbr(string, max_len=2)

Mengembalikan versi singkatan (hanya inisial) dari string yang diberikan dengan maksimal max_len huruf. Hal ini banyak digunakan dalam TechMaju Framework dan ERPNext untuk menghasilkan thumbnail atau gambar placeholder.

frappe.utils.get_abbr('Greg') # 'G'
frappe.utils.get_abbr('Coca Cola Company') # 'CC'
frappe.utils.get_abbr('Red Fox Jumps', max_len=3) # 'RFJ'

validate_url

validate_url(txt, throw=False, valid_schemes=None)

`txt`: Sebuah string untuk memeriksa validitasnya
`throw`: Apakah akan melemparkan pengecualian jika `txt` tidak mewakili URL yang valid, `False` secara default
`valid_schemes`: Sebuah string atau iterable (list, tuple atau set). Jika diberikan, memeriksa skema URL yang diberikan terhadap ini.

Fungsi utilitas ini dapat digunakan untuk memeriksa apakah sebuah string mewakili alamat URL yang valid.

frappe.utils.validate_url('google') # False
frappe.utils.validate_url('https://google.com') # True
frappe.utils.validate_url('https://google.com', throw=True) # melemparkan ValidationError

validate_email_address

validate_email_address(email_str, throw=False)

Mengembalikan string yang berisi alamat email atau daftar alamat email yang valid yang dipisahkan oleh koma yang ada dalam email_str. Jika throw adalah True, frappe.InvalidEmailAddressError dilemparkan jika tidak ada alamat email yang valid dalam string yang diberikan jika tidak, string kosong dikembalikan.

# Alamat email tunggal yang valid
frappe.utils.validate_email_address('admin@techmaju.com') # 'admin@techmaju.com'
frappe.utils.validate_email_address('teks lainnya, admin@techmaju.com, teks lainnya') <span="hljs-comment"># 'admin<span="hljs-comment hljs-doctag">@techmaju.com'

# Alamat email yang valid banyak
frappe.utils.validate_email_address(
    'teks lainnya, admin@techmaju.com, teks lainnya, user@techmaju.com, string non-email lainnya.'
) # 'admin@techmaju.com, user@techmaju.com'

# Alamat email tidak valid
frappe.utils.validate_email_address('teks lainnya') # ''

validate_phone_number

validate_phone_number(phone_number, throw=False)

Mengembalikan True jika phone_number (string) adalah nomor telepon yang valid. Jika phone_number tidak valid dan throw adalah True, frappe.InvalidPhoneNumberError dilemparkan.

# Nomor telepon yang valid
frappe.utils.validate_phone_number('753858375') # True
frappe.utils.validate_phone_number('+91-75385837') # True

# Nomor telepon yang tidak valid
frappe.utils.validate_phone_number('invalid') # False
frappe.utils.validate_phone_number('87345%%', throw=True) # InvalidPhoneNumberError

frappe.cache()

cache()

Mengembalikan koneksi redis, yang merupakan instance dari kelas RedisWrapper yang diwarisi dari kelas redis.Redis. Anda dapat menggunakan koneksi ini untuk menggunakan cache Redis untuk menyimpan/mengambil pasangan kunci-nilai.

cache = frappe.cache()

cache.set('name', 'techmaju') # True
cache.get('name') # b'techmaju'

frappe.sendmail()

sendmail(recipients=[], sender="", subject="No Subject", message="No Message", as_markdown=False, template=None, args=None, **kwargs)

`recipients`: Daftar penerima
`sender`: Pengirim Email. Default adalah pengguna saat ini atau akun keluar default
`subject`: Subjek Email
`message`: (atau `content`) Konten Email
`as_markdown`: Mengonversi konten markdown ke HTML
`template`: Nama template html (jinja) dari folder templates/emails
`args`: Argumen untuk merender template

Untuk sebagian besar kasus, argumen di atas sudah cukup tetapi ada banyak argumen kata kunci lain yang dapat diteruskan ke fungsi ini. Untuk melihat semua argumen kata kunci, silakan lihat implementasi fungsi ini (frappe/__init__.py).

Fungsi ini dapat digunakan untuk mengirim email menggunakan Email Account default pengguna atau Email Account default global.

recipients = [
    'user1@techmaju.com',
    'user2@techmaju.com'
]

frappe.sendmail(
    recipients=recipients,
    subject=frappe._('Pengingat Ulang Tahun'),
    template='birthday_reminder',
    args=dict(
        reminder_text=reminder_text,
        birthday_persons=birthday_persons,
        message=message,
    ),
    header=_('Pengingat Ulang Tahun 🎂')
)

File template Jinja sampel:

<!-- templates/emails/birthday_reminder.html -->
<div>
<div class="gray-container text-center">
<div>
        {% for person in birthday_persons %}
            {% if person.image  %}
                <img src="{{ person.image }}" title="{{ person.name }}"/>
            {% endif %}
        {% endfor %}
    </div>
<div style="margin-top: 15px;">
<span>{{ reminder_text }}</span>
<p class="text-muted">{{ message }}</p>
</div>
</div>

Melampirkan File

Anda dapat dengan mudah melampirkan file ke email Anda dengan meneruskan daftar lampiran ke fungsi sendmail:

frappe.sendmail(
    ["user1@techmaju.com", "user2@techmaju.com"],
    message="## hello, *user*"
    attachments=[{"file_url": "/files/hello.png"}],
    as_markdown=True
)

Perhatikan bagaimana lampiran adalah daftar kamus yang memiliki kunci file_url. Anda dapat menemukan file_url ini di field file_url dokumen File.

filelock

Kunci file dapat digunakan untuk menyinkronkan proses untuk menghindari kondisi balapan.

Contoh: Menulis ke file dapat menyebabkan kondisi balapan jika beberapa penulis mencoba menulis ke file. Jadi kami membuat kunci bernama sehingga proses dapat melihat kunci dan menunggu sampai tersedia untuk menulis.

def update_important_config(config, file):
    with frappe.utils.synchronization.filelock("config_name"):
        json.dumps(config, file)