.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.3 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "TASKLIB" "1" "Dec 14, 2025" "2.5.1" "tasklib"
.SH "نام (NAME)"
tasklib \- مستندات tasklib
.sp
کتابخانه tasklib یک کتابخانه پایتون برای تعامل با پایگاه‌داده‌های taskwarrior \%<http://\:taskwarrior\:.org> با استفاده از یک API از نوع queryset مشابه ORM در Django است.
.sp
از Python 3.5 به بالا، به همراه taskwarrior نسخه 2.4.x به بالا پشتیبانی می‌کند.
نسخه‌های قدیمی‌تر taskwarrior آزمایش نشده‌اند و ممکن است کار نکنند.
.SH "پیش‌نیازها (REQUIREMENTS)"
.INDENT 0.0
.IP \(bu 2
برنامه taskwarrior \%<http://\:taskwarrior\:.org> نسخه v2.4.x یا بالاتر، هرچند استفاده از جدیدترین انتشار جزئی توصیه می‌شود.
.UNINDENT
.SH "نصب (INSTALLATION)"
.sp
نصب از طریق pip (توصیه شده):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pip install tasklib
.EE
.UNINDENT
.UNINDENT
.sp
یا کلون کردن از github:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
git clone https://github.com/robgolding/tasklib.git
cd tasklib
python setup.py install
.EE
.UNINDENT
.UNINDENT
.SH "مقداردهی اولیه (INITIALIZATION)"
.sp
به‌صورت اختیاری نمونهٔ \fBTaskWarrior\fP را با \fBdata_location\fP (دایرکتوری
پایگاه‌داده) مقداردهی اولیه کنید. اگر این دایرکتوری از پیش وجود نداشته باشد،
به‌طور خودکار ایجاد خواهد شد مگر اینکه \fBcreate=False\fP تنظیم شده باشد\&.
.sp
مسیر پیش‌فرض مشابه مسیر پیش‌فرض taskwarrior است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw = TaskWarrior(data_location=\(aq~/.task\(aq, create=True)
.EE
.UNINDENT
.UNINDENT
.sp
نمونهٔ \fBTaskWarrior\fP همچنین از پیکربندی .taskrc شما استفاده خواهد کرد (به‌طوری
که همان UDAهای فایل باینری task شما را شناسایی کند، از همان پیکربندی استفاده کند
و غیره). برای بازنویسی مسیر فایل .taskrc، از
\fBtaskrc_location=~/some/different/path\fP استفاده کنید\&..SH "ایجاد وظایف (CREATING TASKS)"
.sp
برای ایجاد یک وظیفه، کافی است یک شیء جدید از \fBTask\fP بسازید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> new_task = Task(tw, description=\(dqthrow out the trash\(dq)
.EE
.UNINDENT
.UNINDENT
.sp
این وظیفه تا زمانی که متد \fB\&.save()\fP را فراخوانی نکنید، در TaskWarrior ذخیره نخواهد شد (مشابه با Django):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> new_task.save()
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید هر ویژگی را به عنوان یک آرگومان کلیدواژه‌ای برای شیء Task تعیین کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> complex_task = Task(tw, description=\(dqfinally fix the shower\(dq, due=datetime(2015,2,14,8,0,0), priority=\(aqH\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
یا اینکه ویژگی‌ها را یکی‌یکی مقداردهی نمایید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> complex_task = Task(tw)
>>> complex_task[\(aqdescription\(aq] = \(dqfinally fix the shower\(dq
>>> complex_task[\(aqdue\(aq] = datetime(2015,2,14,8,0,0)
>>> complex_task[\(aqpriority\(aq] = \(aqH\(aq
.EE
.UNINDENT
.UNINDENT
.SH "تغییر وظیفه (MODIFYING TASK)"
.sp
برای تغییر یک شیء \fBTask\fP ایجادشده یا بازیابی‌شده، از دسترسی شبه‌دیکشنری استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> homework = tw.tasks.get(tags=[\(aqchores\(aq])
>>> homework[\(aqproject\(aq] = \(aqHome\(aq
.EE
.UNINDENT
.UNINDENT
.sp
تغییرات اعمال‌شده تا زمانی که متد \fBsave()\fP را فراخوانی نکنید، به TaskWarrior منتقل نخواهند شد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> homework.save()
.EE
.UNINDENT
.UNINDENT
.sp
ویژگی‌هایی که به اشیاء بومی پایتون متناظر هستند تبدیل خواهند شد. بخش «ویژگی‌های وظیفه» را ببینید.
.SH "ویژگی‌های وظیفه (TASK ATTRIBUTES)"
.sp
ویژگی‌های اشیاء وظیفه از طریق نمایه‌ها (indexها) قابل دسترسی هستند، بدین صورت:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = tw.tasks.pending().get(tags__contain=\(aqwork\(aq)  # There is only one pending task with \(aqwork\(aq tag
>>> task[\(aqdescription\(aq]
\(aqUpgrade Ubuntu Server\(aq
>>> task[\(aqid\(aq]
15
>>> task[\(aqdue\(aq]
datetime.datetime(2015, 2, 5, 0, 0, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> task[\(aqtags\(aq]
[\(aqwork\(aq, \(aqservers\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
فیلدهای زیر به اشیاء پایتون تبدیل (deserialize) می‌شوند:
.INDENT 0.0
.IP \(bu 2
\fBdue\fP، \fBwait\fP، \fBscheduled\fP، \fBuntil\fP، \fBentry\fP: به یک شیء \fBdatetime\fP تبدیل می‌شوند
.IP \(bu 2
\fBannotations\fP: به فهرستی از اشیاء \fBTaskAnnotation\fP تبدیل می‌شوند
.IP \(bu 2
\fBtags\fP: به فهرستی از رشته‌ها تبدیل می‌شوند
.IP \(bu 2
\fBdepends\fP: به مجموعه‌ای از اشیاء \fBTask\fP تبدیل می‌شوند
.UNINDENT
.sp
ویژگی‌ها باید با استفاده از نمایش صحیح پایتونی مقداردهی شوند؛ این مقادیر هنگام ذخیره شدن وظیفه، به قالب مناسب سریال‌سازی (serialize) خواهند شد..SH "ویژگی‌های وظیفه (TASK PROPERTIES)"
.sp
کتابخانه Tasklib برای راحتی، چندین ویژگی روی شیء \fBTask\fP تعریف می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> t.save()
>>> t.saved
True
>>> t.pending
True
>>> t.active
False
>>> t.start()
>>> t.active
True
>>> t.done()
>>> t.completed
True
>>> t.pending
False
>>> t.delete()
>>> t.deleted
True
.EE
.UNINDENT
.UNINDENT
.SH "عملیات روی وظایف (OPERATIONS ON TASKS)"
.sp
پس از تغییر دادن یک یا چند مشخصه، به سادگی \fBsave()\fP را فراخوانی کنید تا آن تغییرات در پایگاه‌داده ذخیره شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = tw.tasks.pending().get(tags__contain=\(aqwork\(aq)
>>> task[\(aqdue\(aq] = datetime(year=2014, month=1, day=5)
>>> task.save()
.EE
.UNINDENT
.UNINDENT
.sp
برای علامت‌گذاری یک وظیفه به عنوان انجام‌شده، از \fBdone()\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = tw.tasks.pending().get(tags__contain=\(aqwork\(aq)
>>> task.done()
>>> len(tw.tasks.pending().filter(tags__contain=\(aqwork\(aq))
0
.EE
.UNINDENT
.UNINDENT
.sp
برای حذف یک وظیفه، از \fBdelete()\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = tw.tasks.get(description=\(dqtask added by mistake\(dq)
>>> task.delete()
.EE
.UNINDENT
.UNINDENT
.sp
برای به‌روزرسانی یک شیء وظیفه با مقادیر پایگاه‌داده TaskWarrior، از \fBrefresh()\fP\& استفاده کنید. مثال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = Task(tw, description=\(dqlearn to cook\(dq)
>>> task.save()
>>> task[\(aqid\(aq]
5
>>> task[\(aqtags\(aq]
[]
.EE
.UNINDENT
.UNINDENT
.sp
اکنون فرض کنید وظیفه را با استفاده از رابط TaskWarrior در یک پایانه دیگر تغییر می‌دهیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ task 5 modify +someday
Task 5 modified.
.EE
.UNINDENT
.UNINDENT
.sp
بازگشت به پردازه باز python:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task[\(aqtags\(aq]
[]
>>> task.refresh()
>>> task[\(aqtags\(aq]
[\(aqsomeday\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
وظایف همچنین می‌توانند شروع و متوقف شوند. به ترتیب از \fBstart()\fP و \fBstop()\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task.start()
>>> task[\(aqstart\(aq]
datetime.datetime(2015, 7, 16, 18, 48, 28, tzinfo=<DstTzInfo \(aqEurope/Prague\(aq CEST+2:00:00 DST>)
>>> task.stop()
>>> task[\(aqstart\(aq]
>>> task.done()
>>> task[\(aqend\(aq]
datetime.datetime(2015, 7, 16, 18, 49, 2, tzinfo=<DstTzInfo \(aqEurope/Prague\(aq CEST+2:00:00 DST>)
.EE
.UNINDENT
.UNINDENT.SH "بازیابی وظایف (RETRIEVING TASKS)"
.sp
\fBtw.tasks\fP یک شیء \fBTaskQuerySet\fP است که API مربوط به Django QuerySet را شبیه‌سازی می‌کند. برای دریافت همه وظایف (از جمله موارد تکمیل‌شده):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.all()
[\(aqFirst task\(aq, \(aqCompleted task\(aq, \(aqDeleted task\(aq, ...]
.EE
.UNINDENT
.UNINDENT
.SH "فیلتر کردن (FILTERING)"
.sp
وظایف را با استفاده از همان ساختار نحوی آشنا فیلتر کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.filter(status=\(aqpending\(aq, tags__contains=[\(aqwork\(aq])
[\(aqUpgrade Ubuntu Server\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان‌های فیلتر به دستور \fBtask\fP ارسال می‌شوند (\fB__\fP با یک نقطه جایگزین می‌شود)، بنابراین مثال بالا معادل دستور زیر است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ task status:pending tags.contain=work
.EE
.UNINDENT
.UNINDENT
.sp
وظایف همچنین می‌توانند با استفاده از دستورات خام فیلتر شوند، مانند زیر:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.filter(\(aqstatus:pending +work\(aq)
[\(aqUpgrade Ubuntu Server\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
اگرچه این روش توصیه نمی‌شود، زیرا با استفاده از دستورات خام ممکن است بخشی از سازگاری و انتقال‌پذیری دستورهای خود را در نسخه‌های مختلف TaskWarrior از دست بدهید.
.sp
با این حال، می‌توانید همانند مثال ارائه‌شده، دستورات خام را با فیلترهای کلیدواژه‌ای ترکیب کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.filter(\(aq+BLOCKING\(aq, project=\(aqHome\(aq)  # Gets all blocking tasks in project Home
[\(aqFix the toilette\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
این می‌تواند روش مناسبی برای استفاده از ساختار نحوی باشد که هنوز توسط tasklib پشتیبانی نمی‌شود. نمونه بالا یک مثال عالی است، زیرا برچسب‌های مجازی همانند برچسب‌های عادی کار نمی‌کنند؛ یعنی:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.filter(tags=[\(aqBLOCKING\(aq])
>>> []
.EE
.UNINDENT
.UNINDENT
.sp
کار نخواهد کرد.
.sp
توابع توکاری برای بازیابی وظایف معلق (pending) و تکمیل‌شده وجود دارند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.pending().filter(tags__contain=\(aqwork\(aq)
[\(aqUpgrade Ubuntu Server\(aq]
>>> len(tw.tasks.completed())
227
.EE
.UNINDENT
.UNINDENT
.sp
از \fBget()\fP برای بازگرداندن تنها وظیفه موجود در یک \fBTaskQuerySet\fP یا ایجاد یک استثنا استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.get(tags__contain=\(aqwork\(aq)[\(aqstatus\(aq]
\(aqpending\(aq
>>> tw.tasks.get(status=\(aqcompleted\(aq, tags__contains=\(aqwork\(aq)  # Status of only task with the work tag is pending, so this should fail
Traceback (most recent call last):
  File \(dq<stdin>\(dq, line 1, in <module>
  File \(dqtasklib/task.py\(dq, line 224, in get
    \(aqLookup parameters were {0}\(aq.format(kwargs))
tasklib.task.DoesNotExist: Task matching query does not exist. Lookup parameters were {\(aqstatus\(aq: \(aqcompleted\(aq, \(aqtags__contains\(aq: [\(aqwork\(aq]}
>>> tw.tasks.get(status=\(aqpending\(aq)
Traceback (most recent call last):
  File \(dq<stdin>\(dq, line 1, in <module>
  File \(dqtasklib/task.py\(dq, line 227, in get
    \(aqLookup parameters were {1}\(aq.format(num, kwargs))
ValueError: get() returned more than one Task \-\- it returned 23! Lookup parameters were {\(aqstatus\(aq: \(aqpending\(aq}
.EE
.UNINDENT
.UNINDENT
.sp
علاوه بر این، از آنجا که فیلترها \fBTaskQuerySet\fP بازمی‌گردانند، می‌توانید فیلترها را روی یکدیگر اعمال (stack) کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> home_tasks = tw.tasks.filter(project=\(aqWife\(aq)
>>> home_tasks.filter(due__before=datetime(2015,2,14,14,14,14))  # What I have to do until Valentine\(aqs day
[\(aqPrepare surprise birthday party\(aq]
.EE
.UNINDENT
.UNINDENT.SH "برابری اشیاء وظیفه (EQUALITY OF TASK OBJECTS)"
.sp
دو شیء Task در صورتی برابر در نظر گرفته می‌شوند که دارای UUID یکسان باشند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task1 = Task(tw, description=\(dqPet the dog\(dq)
>>> task1.save()
>>> task2 = tw.tasks.get(description=\(dqPet the dog\(dq)
>>> task1 == task2
True
.EE
.UNINDENT
.UNINDENT
.sp
اگر دو وظیفهٔ ذخیره‌نشده را مقایسه کنید، تنها در صورتی برابر در نظر گرفته می‌شوند که دقیقاً همان شیء Python باشند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task1 = Task(tw, description=\(dqPet the cat\(dq)
>>> task2 = Task(tw, description=\(dqPet the cat\(dq)
>>> task1 == task2
False
>>> task3 = task1
>>> task3 == task1
True
.EE
.UNINDENT
.UNINDENT
.SH "دسترسی به مقادیر اصلی (ACCESSING ORIGINAL VALUES)"
.sp
برای دسترسی به وضعیت ذخیره‌شدهٔ Task، از دسترسی شبه‌دیکشنری با استفاده از ویژگی \fBoriginal\fP استفاده کنید:
.sp
.EX
>>> t = Task(tw, description=\(dqtidy up\(dq)
>>> t.save()
>>> t[\(aqdescription\(aq] = \(dqtidy up the kitchen and bathroom\(dq
>>> t[\(aqdescription\(aq]
\(dqtidy up the kitchen and bathroom\(dq
>>> t.original[\(aqdescription\(aq]
\(dqtidy up\(dq
.EE
.sp
هنگامی که وظیفه را ذخیره می‌کنید، مقادیر اصلی به‌روزرسانی می‌شوند تا بازتاب‌دهندهٔ وضعیت ذخیره‌شدهٔ وظیفه باشند:
.sp
.EX
>>> t.save()
>>> t.original[\(aqdescription\(aq]
\(dqtidy up the kitchen and bathroom\(dq
.EE
.SH "کار با تاریخ و زمان (DEALING WITH DATES AND TIME)"
.sp
تمام ویژگی‌های شبه‌برچسب زمانی (timestamp\-like) وظایف، به اشیاء datetime دارای منطقهٔ زمانی (timezone\-aware) تبدیل می‌شوند. برای دستیابی به این هدف، Tasklib از ماژول پایتون \fBzoneinfo\fP بهره می‌برد که پایگاه‌دادهٔ منطقهٔ زمانی Olsen را به پایتون می‌آورد.
.sp
این ویژگی شما را از درگیر شدن با جزئیات آزاردهندهٔ تغییرات ساعت تابستانی (Daylight Saving Time) یا تبدیل میان مناطق زمانی مختلف مصون می‌دارد. برای نمونه، جهت فهرست کردن تمام وظایفی که سررسید آن‌ها تا نیمه‌شب است (در صورتی که اکنون در برلین باشید):
.sp
.EX
>>> myzone = zoneinfo.ZoneInfo(\(aqEurope/Berlin\(aq)
>>> midnight = datetime(2015,2,2,0,0,0,tzinfo=myzone)
>>> tw.tasks.filter(due__before=midnight)
.EE
.sp
با این حال، این روش هنوز کمی خسته‌کننده است. به همین دلیل شیء TaskWarrior با استفاده از ماژول پایتون \fBtzlocal\fP قادر به تشخیص خودکار منطقهٔ زمانی است. اگر منطقهٔ زمانی سیستم شما روی \(aqEurope/Berlin\(aq تنظیم شده باشد، مثال زیر دقیقاً همانند مثال پیشین عمل خواهد کرد:
.sp
.EX
>>> tw.tasks.filter(due__before=datetime(2015,2,2,0,0,0))
.EE
.sp
همچنین می‌توانید هنگام فیلتر کردن از تاریخ‌های ساده استفاده کنید:
.sp
.EX
>>> tw.tasks.filter(due__before=date(2015,2,2))
.EE
.sp
در چنین حالتی، مقدار 00:00:00 به عنوان مؤلفهٔ زمان در نظر گرفته می‌شود.
.sp
البته می‌توانید هنگام مقداردهی اولیه به شیء Task یا انتساب مقادیر به ویژگی‌های datetime، از اشیاء datetime فاقد منطقهٔ زمانی (naive) نیز استفاده کنید:
.sp
.EX
>>> t = Task(tw, description=\(dqBuy new shoes\(dq, due=date(2015,2,5))
>>> t[\(aqdue\(aq]
datetime.datetime(2015, 2, 5, 0, 0, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> t[\(aqdue\(aq] = date(2015,2,6,15,15,15)
>>> t[\(aqdue\(aq]
datetime.datetime(2015, 2, 6, 15, 15, 15, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
.EE
.sp
با این حال، از آنجا که در پایتون مقادیر datetime دارای منطقهٔ زمانی (timezone\-aware) و فاقد منطقهٔ زمانی (timezone\-naive) با یکدیگر قابل مقایسه نیستند، این امر می‌تواند باعث رفتارهای غیرمنتظره‌ای شود:
.sp
.EX
>>> from datetime import datetime
>>> now = datetime.now()
>>> t = Task(tw, description=\(dqtake out the trash now\(dq)
>>> t[\(aqdue\(aq] = now
>>> now
datetime.datetime(2015, 2, 1, 19, 44, 4, 770001)
>>> t[\(aqdue\(aq]
datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> t[\(aqdue\(aq] == now
Traceback (most recent call last):
  File \(dq<stdin>\(dq, line 1, in <module>
  TypeError: can\(aqt compare offset\-naive and offset\-aware datetimes
.EE
.sp
اگر می‌خواهید یک مقدار datetime دارای منطقهٔ زمانی را با یک مقدار بدون منطقهٔ زمانی مقایسه کنید، باید ابتدا مقدار بدون منطقهٔ زمانی را محلی‌سازی (localize) کنید:
.sp
.EX
>>> from datetime import datetime
>>> now = datetime.now().astimezone()
>>> t[\(aqdue\(aq] = now
>>> now
datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> t[\(aqdue\(aq] == now
True
.EE
.sp
همچنین توجه داشته باشید که اهمیتی ندارد اشیاء datetime دارای منطقهٔ زمانی، روی منطقهٔ زمانی یکسانی تنظیم شده باشند یا خیر:
.sp
.EX
>>> import zoneinfo
>>> t[\(aqdue\(aq]
datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> now.astimezone(zoneinfo.ZoneInfo(\(aqUTC\(aq))
datetime.datetime(2015, 2, 1, 18, 44, 4, 770001, tzinfo=<UTC>)
>>> t[\(aqdue\(aq] == now.astimezone(zoneinfo.ZoneInfo(\(aqUTC\(aq))
True
.EE
.sp
\fIنکته\fP: رفتار زیر تنها در TaskWarrior >= 2.4.0 در دسترس است.
.sp
رویکرد سومی نیز برای تنظیم مقادیر تاریخ و زمان وجود دارد که از دستور \(aqtask calc\(aq استفاده می‌کند. می‌توانید به‌سادگی هر ویژگی datetime را به هر رشته‌ای که شامل یک عبارت زمانی معتبر با قالب‌بندی TaskWarrior باشد، نسبت دهید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ task calc now + 1d
2015\-07\-17T21:17:54
.EE
.UNINDENT
.UNINDENT
.sp
از این نحو (syntax) می‌توان در مفسر پایتون به شکل زیر استفاده کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> t[\(aqdue\(aq] = \(dqnow + 1d\(dq
>>> t[\(aqdue\(aq]
datetime.datetime(2015, 7, 17, 21, 19, 31, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CEST+2:00:00 DST>)
.EE
.UNINDENT
.UNINDENT
.sp
به‌وضوح مشخص است رشته‌ای که دارای عبارت زمانی با قالب TaskWarrior است، به‌طور خودکار به شیء datetime بومی در منطقهٔ زمانی محلی تبدیل می‌شود.
.sp
برای دسترسی به فهرست قالب‌ها و کلمات کلیدی مجاز، لطفاً مراجعه کنید به:
.INDENT 0.0
.IP \(bu 2
\%<http://\:taskwarrior\:.org/\:docs/\:dates\:.html>
.IP \(bu 2
\%<http://\:taskwarrior\:.org/\:docs/\:named_dates\:.html>
.UNINDENT.sp
با این حال، از آنجا که هر یک از این انتساب‌ها برای تبدیل نیازمند فراخوانی \(aqtask calc\(aq است، انتساب مکرر و خودکار رشته‌ها به ویژگی‌های datetime ممکن است باعث بروز مشکلاتی در کارایی شود.
.SH "کار با حاشیه‌نویسی‌ها (WORKING WITH ANNOTATIONS)"
.sp
حاشیه‌نویسی‌های وظایف در tasklib توسط شیءهای \fBTaskAnnotation\fP نشان داده می‌شوند. این شیءها بسیار شبیه به شیءهای \fBTask\fP هستند، هرچند بسیار ساده‌تر شده‌اند.
.sp
.EX
>>> annotated_task = tw.tasks.get(description=\(aqAnnotated task\(aq)
>>> annotated_task[\(aqannotations\(aq]
[Yeah, I am annotated!]
.EE
.sp
حاشیه‌نویسی‌ها تنها دارای مقادیر تعریف‌شدهٔ \fBentry\fP و \fBdescription\fP هستند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> annotation = annotated_task[\(aqannotations\(aq][0]
>>> annotation[\(aqentry\(aq]
datetime.datetime(2015, 1, 3, 21, 13, 55, tzinfo=<DstTzInfo \(aqEurope/Berlin\(aq CET+1:00:00 STD>)
>>> annotation[\(aqdescription\(aq]
u\(aqYeah, I am annotated!\(aq
.EE
.UNINDENT
.UNINDENT
.sp
برای افزودن یک حاشیه‌نویسی به یک Task، از \fBadd_annotation()\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task = Task(tw, description=\(dqnew task\(dq)
>>> task.add_annotation(\(dqwe can annotate any task\(dq)
Traceback (most recent call last):
  File \(dq<stdin>\(dq, line 1, in <module>
    File \(dqbuild/bdist.linux\-x86_64/egg/tasklib/task.py\(dq, line 355, in add_annotation
tasklib.task.NotSaved: Task needs to be saved to add annotation
.EE
.UNINDENT
.UNINDENT
.sp
با این حال، پیش از آنکه بتوانید حاشیه‌نویسی را به یک Task بیفزایید، باید آن را ذخیره کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task.save()
>>> task.add_annotation(\(dqwe can annotate saved tasks\(dq)
>>> task[\(aqannotations\(aq]
[we can annotate saved tasks]
.EE
.UNINDENT
.UNINDENT
.sp
برای حذف حاشیه‌نویسی، شرح آن را به متد \fBremove_annotation()\fP ارسال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task.remove_annotation(\(dqwe can annotate saved tasks\(dq)
.EE
.UNINDENT
.UNINDENT
.sp
همچنین می‌توانید خود شیء \fBTaskAnnotation\fP را ارسال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> task.remove_annotation(task[\(aqannotations\(aq][0])
.EE
.UNINDENT
.UNINDENT
.SH "اجرای دستورهای سفارشی (RUNNING CUSTOM COMMANDS)"
.sp
برای اجرای دستورهای سفارشی، از متد \fBexecute_command()\fP شیء \fBTaskWarrior\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw = TaskWarrior()
>>> tw.execute_command([\(aqlog\(aq, \(aqFinish high school.\(aq])
[u\(aqLogged task.\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید از آرگومان کلیدواژه‌ای \fBconfig_override\fP برای مشخص کردن دیکشنری‌ای از بازنویسی‌های پیکربندی استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.execute_command([\(aq3\(aq, \(aqdone\(aq], config_override={\(aqgc\(aq: \(aqoff\(aq}) # Will mark 3 as completed and it will retain its ID
.EE
.UNINDENT
.UNINDENT
.sp
علاوه بر این، می‌توانید از پرچم \fBreturn_all=True\fP استفاده کنید که سه‌تایی \fB(stdout, sterr, return_code)\fP را بازمی‌گرداند، و همچنین \fBallow_failure=False\fP که در صورت بازگرداندن کد وضعیت خروج غیرصفر توسط فایل اجرایی task، از بالا آمدن استثنا توسط tasklib جلوگیری می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.execute_command([\(aqinvalidcommand\(aq], allow_failure=False, return_all=True)
([u\(aq\(aq],
 [u\(aqUsing alternate .taskrc file /home/tbabej/.taskrc\(aq,
  u\(dq[task next rc:/home/tbabej/.taskrc rc.recurrence.confirmation=no rc.json.array=off rc.confirmation=no rc.bulk=0 rc.dependency.confirmation=no description ~ \(aqinvalidcommand\(aq]\(dq,
  u\(aqConfiguration override rc.recurrence.confirmation:no\(aq,
  u\(aqConfiguration override rc.json.array:off\(aq,
  u\(aqConfiguration override rc.confirmation:no\(aq,
  u\(aqConfiguration override rc.bulk:0\(aq,
  u\(aqConfiguration override rc.dependency.confirmation:no\(aq,
  u\(aqNo matches.\(aq,
  u\(aqThere are local changes.  Sync required.\(aq],
 1)
.EE
.UNINDENT
.UNINDENT.SH "تنظیم مقادیر پیکربندی سفارشی (SETTING CUSTOM CONFIGURATION VALUES)"
.sp
به‌طور پیش‌فرض، TaskWarrior از مقادیر پیکربندی ذخیره‌شده در .taskrc شما استفاده می‌کند.
برای مشاهدهٔ اینکه چه مقادیر بازنویسی پیکربندی‌ای (overrides) به هر دستور task
اجرا شده ارسال می‌شوند، نگاهی به صفت \fBoverrides\fP در شیء \fBTaskWarrior\fP بیندازید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.overrides
{\(aqconfirmation\(aq: \(aqno\(aq, \(aqdata.location\(aq: \(aq/home/tbabej/.task\(aq}
.EE
.UNINDENT
.UNINDENT
.sp
برای اعمال مقادیر بازنویسی پیکربندی سفارشی خود، تنها کافی است این دیکشنری را به‌روزرسانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.overrides.update({\(aqhooks\(aq: \(aqoff\(aq})  # tasklib will not trigger hooks
.EE
.UNINDENT
.UNINDENT
.SH "ایجاد اسکریپت‌های قلاب (CREATING HOOK SCRIPTS)"
.sp
از نسخهٔ 2.4.0، برنامهٔ TaskWarrior از اسکریپت‌های قلاب (hook scripts) پشتیبانی می‌کند.
tasklib ابزارهای کمکی بسیار مفیدی را برای نوشتن آن‌ها فراهم کرده است.
با tasklib، نوشتن این اسکریپت‌ها بسیار آسان می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#!/usr/bin/python

from tasklib.task import Task
task = Task.from_input()
# ... <custom logic>
print task.export_data()
.EE
.UNINDENT
.UNINDENT
.sp
برای نمونه، پلاگینی که اولویت \(dqH\(dq را به هر تسکی که شامل سه علامت تعجب
در توضیحاتش باشد اختصاص می‌دهد، به شکل زیر خواهد بود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#!/usr/bin/python

from tasklib.task import Task
task = Task.from_input()

if \(dq!!!\(dq in task[\(aqdescription\(aq]:
    task[\(aqpriority\(aq] = \(dqH\(dq

print task.export_data()
.EE
.UNINDENT
.UNINDENT
.sp
کتابخانهٔ tasklib می‌تواند به‌طور خودکار تشخیص دهد که در رویداد \fBon\-modify\fP در حال
اجرا است یا خیر؛ این رویداد ورودی بیشتری نسبت به رویداد \fBon\-add\fP فراهم می‌کند و
داده‌ها را بر همان اساس می‌خواند.
.sp
این بدان معناست که مثال بالا هم برای رویداد \fBon\-add\fP و هم برای \fBon\-modify\fP کار می‌کند!
.sp
در نتیجه، می‌توانید تنها یک فایل قلاب برای هر دو رویداد \fBon\-add\fP و
\fBon\-modify\fP ایجاد کرده و برای دیگری فقط یک پیوند نمادین (symlink) بسازید.
این کار نیاز به نگهداری دو نسخه از یک کد و یا کدهای تکراری (boilerplate) را از بین می‌برد.
.sp
در رویدادهای \fBon\-modify\fP، کتابخانهٔ tasklib هم نسخهٔ اصلی و هم نسخهٔ تغییریافتهٔ
تسک را در شیء \fBTask\fP بازگردانده‌شده بارگذاری می‌کند. برای دسترسی به داده‌های اولیه
(به‌صورت فقط‌خواندنی)، از صفت شبه‌دیکشنری \fBoriginal\fP استفاده کنید:
.sp
.EX
>>> t = Task.from_input()
>>> t[\(aqdescription\(aq]
\(dqModified description\(dq
>>> t.original[\(aqdescription\(aq]
\(dqOriginal description\(dq
.EE.SH "کار با UDAها (WORKING WITH UDAS)"
.sp
از آنجا که TaskWarrior فایل .taskrc شما را می‌خواند، نیازی نیست همان‌طور که در بالا توضیح داده شد هیچ UDAای را در دیکشنری config مربوط به TaskWarrior تعریف کنید. فرض کنید یک UDA به نام estimate در .taskrc داریم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
uda.estimate.type = numeric
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانیم به‌سادگی و بدون نیاز به تنظیمات اضافی، با استفاده از UDA به نام estimate تسک‌ها را فیلتر و ایجاد کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw = TaskWarrior()
>>> task = Task(tw, description=\(dqLong task\(dq, estimate=1000)
>>> task.save()
>>> task[\(aqid\(aq]
1
.EE
.UNINDENT
.UNINDENT
.sp
این مورد به عنوان UDA در TaskWarrior ذخیره می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ task 1 export
{\(dqid\(dq:1,\(dqdescription\(dq:\(dqLong task\(dq,\(dqestimate\(dq:1000, ...}
.EE
.UNINDENT
.UNINDENT
.sp
همچنین می‌توانیم UDAها را به عنوان آرگومان در TaskFilter مشخص کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw.tasks.filter(estimate=1000)
Long task
.EE
.UNINDENT
.UNINDENT
.SH "همگام‌سازی (SYNCING)"
.sp
اگر متغیرهای پیکربندی لازم را در .taskrc خود مقداردهی کرده باشید، همگام‌سازی به همین سادگی است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw = TaskWarrior()
>>> tw.execute_command([\(aqsync\(aq])
.EE
.UNINDENT
.UNINDENT
.sp
اگر می‌خواهید از سرور/اعتبارنامه‌های غیراستاندارد استفاده کنید، باید بازنویسی‌های پیکربندی را به نمونهٔ \fBTaskWarrior\fP ارائه دهید. دیکشنری \fBconfig\fP را با مقادیری که می‌خواهید جایگزین شوند به‌روزرسانی کنید، و سپس می‌توانیم دستور sync را با استفاده از متد \fBexecute_command()\fP اجرا کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> tw = TaskWarrior()
>>> sync_config = {
\&...     \(aqtaskd.certificate\(aq: \(aq/home/tbabej/.task/tbabej.cert.pem\(aq,
\&...     \(aqtaskd.credentials\(aq: \(aqPublic/tbabej/34af54de\-3cb2\-4d3d\-82be\-33ddb8fd3e66\(aq,
\&...     \(aqtaskd.server\(aq: \(aqtask.server.com:53589\(aq,
\&...     \(aqtaskd.ca\(aq: \(aq/home/tbabej/.task/ca.cert.pem\(aq,
\&...     \(aqtaskd.trust\(aq: \(aqignore hostname\(aq}
>>> tw.config.update(sync_config)
>>> tw.execute_command([\(aqsync\(aq])
.EE
.UNINDENT
.UNINDENT.SH "نویسنده (AUTHOR)"
Rob Golding
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2014 \- 2021, Rob Golding & Gothenburg Bit Factory
.\" End of generated man page.